# Models

## The CheckoutProviderIndexPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderIndexPageRequest":{"type":"object","description":"Request for `CheckoutProviderIndexPage` - Initializes the checkout provider flow.\nThis is the first page in the checkout flow. Only `basket_id` is required.","required":["basket_id"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket to checkout.\nMust be an existing basket with `status=active`."}}}}}}
```

## The CheckoutProviderSelectionPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderSelectionPageRequest":{"type":"object","description":"Request for `CheckoutProviderSelectionPage` - User selects a checkout provider.\nAfter this step, user is redirected to the external payment provider's page.","required":["basket_id","checkout_provider"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket to checkout.\nMust be an existing basket with `status=active`."},"checkout_provider":{"type":"integer","description":"The ID of the selected checkout provider (e.g., Akifast).\nMust be one of the available providers returned by `/checkout-provider-list/`.\nThe system validates that this provider is available for the current basket."}}}}}}
```

## The CheckoutProviderAddressSelectionPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderAddressSelectionPageRequest":{"type":"object","description":"Request for `CheckoutProviderAddressSelectionPage` - Receives address data from checkout provider callback.\nThis data is sent by the external checkout provider after user enters their address.\n\n**Note:** The address format shown here is Akifast-specific. Other checkout providers may use different formats.","required":["basket_id","session_token","shipping_address","billing_address"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"session_token":{"type":"string","format":"uuid","description":"Session token from the checkout provider callback.\nUsed to verify the callback authenticity."},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput"},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput"}}},"AkifastAddressInput":{"type":"object","description":"**Akifast-specific** address input format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different address formats.","required":["name","surname","phone_number","address_title","line","hash_data","country","city","town","district"],"properties":{"name":{"type":"string","description":"First name of the address holder."},"surname":{"type":"string","description":"Last name of the address holder."},"phone_number":{"type":"string","description":"Contact phone number.\nShould include country code for international format."},"postal_code":{"type":["string","null"],"description":"Postal/ZIP code (optional).\nNot all regions require postal codes."},"address_title":{"type":"string","description":"User-defined title for the address.\nExamples: \"Home\", \"Office\", \"Work\""},"line":{"type":"string","description":"Full street address line.\nShould include street name, building number, apartment, etc."},"address_type":{"type":["string","null"],"enum":["CUSTOMER","RETAIL_STORE","PICKUP_LOCATION","CHECKOUT_PROVIDER",null],"description":"Address type indicator (case-insensitive, converted to lowercase internally).\n- `CUSTOMER`: Standard customer delivery address\n- `RETAIL_STORE`: Retail store address for in-store pickup\n- `PICKUP_LOCATION`: Designated pickup point\n- `CHECKOUT_PROVIDER`: Address provided by checkout provider"},"tax_no":{"type":["string","null"],"description":"Tax identification number for invoice purposes.\nOptional field for corporate/business customers."},"tax_office":{"type":["string","null"],"description":"Tax office name for invoice purposes.\nCommonly used for corporate customers in Turkey (Vergi Dairesi)."},"company_name":{"type":["string","null"],"description":"Company name for corporate customers.\nUsed for invoice generation."},"notes":{"type":["string","null"],"description":"Additional delivery notes.\nExamples: \"Leave at door\", \"Call before delivery\""},"hash_data":{"type":"string","description":"Address verification hash from the checkout provider.\nUsed to verify address data integrity."},"country":{"$ref":"#/components/schemas/AddressLocationField"},"city":{"$ref":"#/components/schemas/AddressLocationField"},"town":{"$ref":"#/components/schemas/AddressLocationField"},"district":{"$ref":"#/components/schemas/AddressLocationField"}}},"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}}}}}
```

## The CheckoutProviderShippingOptionPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderShippingOptionPageRequest":{"type":"object","description":"Request for `CheckoutProviderShippingOptionPage` - Retrieves available shipping options.\nThe `conversation_id` must match the stored value from the payment session for security.","required":["basket_id","conversation_id"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"conversation_id":{"type":"string","description":"Conversation ID from the checkout provider.\nMust match the conversation ID from the payment session initialization.\nValidation error if mismatch: \"Verification failed, please try again\""},"language":{"type":["string","null"],"description":"Language code for localized content (optional).\nExamples: \"tr\" (Turkish), \"en\" (English)."}}}}}}
```

## The CheckoutProviderAgreementListPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderAgreementListPageRequest":{"type":"object","description":"Request for `CheckoutProviderAgreementListPage` - Shows agreements and sets shipping option.\nUser must select a shipping option and an agreement code.","required":["basket_id","session_token","shipping_option_key","user","code"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"session_token":{"type":"string","format":"uuid","description":"Session token from the checkout provider callback."},"shipping_option_key":{"type":"integer","description":"The ID of the selected shipping option.\nMust be one of the available shipping options returned in the previous step."},"code":{"type":"string","enum":["info","sales"],"description":"The agreement code to display.\n- `info`: Preliminary information form (ön bilgilendirme formu)\n- `sales`: Distance selling agreement (mesafeli satış sözleşmesi)"},"user":{"type":"object","description":"User information from the checkout provider.\nEmail is used to update the shipping address contact info.","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"User's email address from checkout provider."}}},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Optional shipping address update.\nIf provided, updates the shipping address in pre-order."},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Optional billing address update.\nIf provided, updates the billing address in pre-order."}}},"AkifastAddressInput":{"type":"object","description":"**Akifast-specific** address input format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different address formats.","required":["name","surname","phone_number","address_title","line","hash_data","country","city","town","district"],"properties":{"name":{"type":"string","description":"First name of the address holder."},"surname":{"type":"string","description":"Last name of the address holder."},"phone_number":{"type":"string","description":"Contact phone number.\nShould include country code for international format."},"postal_code":{"type":["string","null"],"description":"Postal/ZIP code (optional).\nNot all regions require postal codes."},"address_title":{"type":"string","description":"User-defined title for the address.\nExamples: \"Home\", \"Office\", \"Work\""},"line":{"type":"string","description":"Full street address line.\nShould include street name, building number, apartment, etc."},"address_type":{"type":["string","null"],"enum":["CUSTOMER","RETAIL_STORE","PICKUP_LOCATION","CHECKOUT_PROVIDER",null],"description":"Address type indicator (case-insensitive, converted to lowercase internally).\n- `CUSTOMER`: Standard customer delivery address\n- `RETAIL_STORE`: Retail store address for in-store pickup\n- `PICKUP_LOCATION`: Designated pickup point\n- `CHECKOUT_PROVIDER`: Address provided by checkout provider"},"tax_no":{"type":["string","null"],"description":"Tax identification number for invoice purposes.\nOptional field for corporate/business customers."},"tax_office":{"type":["string","null"],"description":"Tax office name for invoice purposes.\nCommonly used for corporate customers in Turkey (Vergi Dairesi)."},"company_name":{"type":["string","null"],"description":"Company name for corporate customers.\nUsed for invoice generation."},"notes":{"type":["string","null"],"description":"Additional delivery notes.\nExamples: \"Leave at door\", \"Call before delivery\""},"hash_data":{"type":"string","description":"Address verification hash from the checkout provider.\nUsed to verify address data integrity."},"country":{"$ref":"#/components/schemas/AddressLocationField"},"city":{"$ref":"#/components/schemas/AddressLocationField"},"town":{"$ref":"#/components/schemas/AddressLocationField"},"district":{"$ref":"#/components/schemas/AddressLocationField"}}},"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}}}}}
```

## The CheckoutProviderNotificationPageRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderNotificationPageRequest":{"type":"object","description":"Request for `CheckoutProviderNotificationPage` - Final step that creates the order.\nThis is sent by the checkout provider after successful payment.\nContains complete transaction, user, address, and payment information.\n\n**Note:** The schema shown here (akifast_user, transaction, etc.) is Akifast-specific.\nOther checkout providers may use different field names and formats.","required":["basket_id","basket","agreements","conversation_id","is_successful","akifast_user","transaction","payment_info","card_info"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"basket":{"type":"object","description":"Basket snapshot for validation.\nThe system compares this with the current basket to detect changes.\nIf items were added/removed/modified during checkout, order creation fails.","required":["basket_items"],"properties":{"basket_items":{"type":"array","description":"List of basket items for validation.\nEach item's SKU, quantity, and basket_item_id are compared.","items":{"type":"object","required":["sku","quantity","basket_item_id"],"properties":{"sku":{"type":"string","description":"Product SKU code."},"quantity":{"type":"integer","description":"Item quantity in the basket."},"basket_item_id":{"type":"string","description":"Basket item identifier.\nFormat: \"item-{id}\" where id is the basket item ID."}}}}}},"agreements":{"type":"boolean","description":"User's acceptance of terms and conditions.\nMust be `true` to proceed with order creation.\nValidation error if false: \"You must accept agreement to continue.\""},"conversation_id":{"type":"string","description":"Conversation ID for security verification.\nMust match the stored value from payment session initialization.\nValidation error if mismatch: \"Verification failed, please try again\""},"is_successful":{"type":"boolean","description":"Payment success indicator from the checkout provider.\nMust be `true` to create the order.\nValidation error if false: \"Transaction failed. Please try again.\""},"akifast_user":{"$ref":"#/components/schemas/AkifastUserInput"},"transaction":{"$ref":"#/components/schemas/AkifastTransactionInput"},"payment_info":{"type":"object","description":"Payment system information.","required":["payment_system_code"],"properties":{"payment_system_code":{"type":"string","description":"Payment system code.\nExamples: \"akbank\", \"garanti\", \"isbank\", \"yapikredi\""}}},"card_info":{"type":"array","description":"Card information array.\nContains the BIN number for card identification.","minItems":1,"items":{"type":"object","required":["bin"],"properties":{"bin":{"type":"string","minLength":6,"maxLength":8,"pattern":"^[0-9]{6,8}$","description":"Card BIN number (first 6 or 8 digits of card number).\nUsed to identify the card type and issuing bank.\nMust be numeric and 6-8 characters."}}}},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Final shipping address.\nIf provided, updates the shipping address before order creation."},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Final billing address.\nIf provided, updates the billing address before order creation."}}},"AkifastUserInput":{"type":"object","description":"**Akifast-specific** user information format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different user data formats.","required":["akinon_user_id","name","surname","email"],"properties":{"akinon_user_id":{"type":"string","maxLength":255,"description":"Unique user identifier from Akifast/Akinon system.\nUsed to link or create social account."},"name":{"type":"string","maxLength":255,"description":"User's first name."},"surname":{"type":"string","maxLength":255,"description":"User's last name."},"email":{"type":"string","format":"email","description":"User's email address.\nAutomatically converted to lowercase during validation."},"phone_number":{"type":["string","null"],"maxLength":255,"description":"User's phone number."},"identity_number":{"type":["string","null"],"maxLength":255,"description":"National identity number (T.C. Kimlik No in Turkey).\nOptional field for compliance requirements."},"status":{"type":["string","null"],"maxLength":255,"description":"User account status in Akifast system."},"verification_status":{"type":["string","null"],"maxLength":255,"description":"User verification status."},"verification_date":{"type":["string","null"],"maxLength":255,"description":"Date when user was verified."},"gender":{"type":["string","null"],"maxLength":255,"description":"User's gender."},"email_verified":{"type":["string","null"],"maxLength":255,"description":"Email verification status."},"birth_date":{"type":["string","null"],"maxLength":255,"description":"User's birth date."}}},"AkifastTransactionInput":{"type":"object","description":"**Akifast-specific** transaction data format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different transaction data formats.\nContains installment, shipping, and raw payment response data.","required":["installment_count","interest_amount","total_paid_amount","payment_system_raw_response","shipping_option_key","is_threed"],"properties":{"shipping_option_key":{"type":"integer","description":"Selected shipping option ID.\nMust be available for the delivery address.\nValidated against available shipping options."},"installment_count":{"type":"integer","minimum":1,"maximum":12,"description":"Number of installments for the payment.\n1 = single payment (no installment)\n2-12 = installment payment"},"interest_rate":{"type":"number","format":"float","minimum":0,"maximum":100,"description":"Interest rate percentage (optional).\n0 = no interest"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount added to the order.\n0 for interest-free installments."},"total_paid_amount":{"type":"number","format":"float","description":"Total amount paid by the customer.\nIncludes order amount + shipping + interest."},"is_threed":{"type":"boolean","description":"Whether 3D Secure authentication was used.\ntrue = 3DS verified transaction\nfalse = non-3DS transaction"},"payment_system_raw_response":{"type":"string","description":"Raw response from the payment system.\nStored for audit and debugging purposes.\nMay be JSON string or other format."}}},"AkifastAddressInput":{"type":"object","description":"**Akifast-specific** address input format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different address formats.","required":["name","surname","phone_number","address_title","line","hash_data","country","city","town","district"],"properties":{"name":{"type":"string","description":"First name of the address holder."},"surname":{"type":"string","description":"Last name of the address holder."},"phone_number":{"type":"string","description":"Contact phone number.\nShould include country code for international format."},"postal_code":{"type":["string","null"],"description":"Postal/ZIP code (optional).\nNot all regions require postal codes."},"address_title":{"type":"string","description":"User-defined title for the address.\nExamples: \"Home\", \"Office\", \"Work\""},"line":{"type":"string","description":"Full street address line.\nShould include street name, building number, apartment, etc."},"address_type":{"type":["string","null"],"enum":["CUSTOMER","RETAIL_STORE","PICKUP_LOCATION","CHECKOUT_PROVIDER",null],"description":"Address type indicator (case-insensitive, converted to lowercase internally).\n- `CUSTOMER`: Standard customer delivery address\n- `RETAIL_STORE`: Retail store address for in-store pickup\n- `PICKUP_LOCATION`: Designated pickup point\n- `CHECKOUT_PROVIDER`: Address provided by checkout provider"},"tax_no":{"type":["string","null"],"description":"Tax identification number for invoice purposes.\nOptional field for corporate/business customers."},"tax_office":{"type":["string","null"],"description":"Tax office name for invoice purposes.\nCommonly used for corporate customers in Turkey (Vergi Dairesi)."},"company_name":{"type":["string","null"],"description":"Company name for corporate customers.\nUsed for invoice generation."},"notes":{"type":["string","null"],"description":"Additional delivery notes.\nExamples: \"Leave at door\", \"Call before delivery\""},"hash_data":{"type":"string","description":"Address verification hash from the checkout provider.\nUsed to verify address data integrity."},"country":{"$ref":"#/components/schemas/AddressLocationField"},"city":{"$ref":"#/components/schemas/AddressLocationField"},"town":{"$ref":"#/components/schemas/AddressLocationField"},"district":{"$ref":"#/components/schemas/AddressLocationField"}}},"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}}}}}
```

## The AkifastAddressInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"AkifastAddressInput":{"type":"object","description":"**Akifast-specific** address input format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different address formats.","required":["name","surname","phone_number","address_title","line","hash_data","country","city","town","district"],"properties":{"name":{"type":"string","description":"First name of the address holder."},"surname":{"type":"string","description":"Last name of the address holder."},"phone_number":{"type":"string","description":"Contact phone number.\nShould include country code for international format."},"postal_code":{"type":["string","null"],"description":"Postal/ZIP code (optional).\nNot all regions require postal codes."},"address_title":{"type":"string","description":"User-defined title for the address.\nExamples: \"Home\", \"Office\", \"Work\""},"line":{"type":"string","description":"Full street address line.\nShould include street name, building number, apartment, etc."},"address_type":{"type":["string","null"],"enum":["CUSTOMER","RETAIL_STORE","PICKUP_LOCATION","CHECKOUT_PROVIDER",null],"description":"Address type indicator (case-insensitive, converted to lowercase internally).\n- `CUSTOMER`: Standard customer delivery address\n- `RETAIL_STORE`: Retail store address for in-store pickup\n- `PICKUP_LOCATION`: Designated pickup point\n- `CHECKOUT_PROVIDER`: Address provided by checkout provider"},"tax_no":{"type":["string","null"],"description":"Tax identification number for invoice purposes.\nOptional field for corporate/business customers."},"tax_office":{"type":["string","null"],"description":"Tax office name for invoice purposes.\nCommonly used for corporate customers in Turkey (Vergi Dairesi)."},"company_name":{"type":["string","null"],"description":"Company name for corporate customers.\nUsed for invoice generation."},"notes":{"type":["string","null"],"description":"Additional delivery notes.\nExamples: \"Leave at door\", \"Call before delivery\""},"hash_data":{"type":"string","description":"Address verification hash from the checkout provider.\nUsed to verify address data integrity."},"country":{"$ref":"#/components/schemas/AddressLocationField"},"city":{"$ref":"#/components/schemas/AddressLocationField"},"town":{"$ref":"#/components/schemas/AddressLocationField"},"district":{"$ref":"#/components/schemas/AddressLocationField"}}},"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}}}}}
```

## The AddressLocationField object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}}}}}
```

## The AkifastUserInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"AkifastUserInput":{"type":"object","description":"**Akifast-specific** user information format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different user data formats.","required":["akinon_user_id","name","surname","email"],"properties":{"akinon_user_id":{"type":"string","maxLength":255,"description":"Unique user identifier from Akifast/Akinon system.\nUsed to link or create social account."},"name":{"type":"string","maxLength":255,"description":"User's first name."},"surname":{"type":"string","maxLength":255,"description":"User's last name."},"email":{"type":"string","format":"email","description":"User's email address.\nAutomatically converted to lowercase during validation."},"phone_number":{"type":["string","null"],"maxLength":255,"description":"User's phone number."},"identity_number":{"type":["string","null"],"maxLength":255,"description":"National identity number (T.C. Kimlik No in Turkey).\nOptional field for compliance requirements."},"status":{"type":["string","null"],"maxLength":255,"description":"User account status in Akifast system."},"verification_status":{"type":["string","null"],"maxLength":255,"description":"User verification status."},"verification_date":{"type":["string","null"],"maxLength":255,"description":"Date when user was verified."},"gender":{"type":["string","null"],"maxLength":255,"description":"User's gender."},"email_verified":{"type":["string","null"],"maxLength":255,"description":"Email verification status."},"birth_date":{"type":["string","null"],"maxLength":255,"description":"User's birth date."}}}}}}
```

## The AkifastTransactionInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"AkifastTransactionInput":{"type":"object","description":"**Akifast-specific** transaction data format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different transaction data formats.\nContains installment, shipping, and raw payment response data.","required":["installment_count","interest_amount","total_paid_amount","payment_system_raw_response","shipping_option_key","is_threed"],"properties":{"shipping_option_key":{"type":"integer","description":"Selected shipping option ID.\nMust be available for the delivery address.\nValidated against available shipping options."},"installment_count":{"type":"integer","minimum":1,"maximum":12,"description":"Number of installments for the payment.\n1 = single payment (no installment)\n2-12 = installment payment"},"interest_rate":{"type":"number","format":"float","minimum":0,"maximum":100,"description":"Interest rate percentage (optional).\n0 = no interest"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount added to the order.\n0 for interest-free installments."},"total_paid_amount":{"type":"number","format":"float","description":"Total amount paid by the customer.\nIncludes order amount + shipping + interest."},"is_threed":{"type":"boolean","description":"Whether 3D Secure authentication was used.\ntrue = 3DS verified transaction\nfalse = non-3DS transaction"},"payment_system_raw_response":{"type":"string","description":"Raw response from the payment system.\nStored for audit and debugging purposes.\nMay be JSON string or other format."}}}}}}
```

## The OrderCancellationRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderCancellationRequest":{"type":"object","description":"Request payload for cancelling order items.\nContains a list of items to cancel with their individual cancellation details.","required":["cancel_order_items"],"properties":{"cancel_order_items":{"type":"array","description":"List of order items to cancel with their cancellation details.","items":{"$ref":"#/components/schemas/OrderItemCancellationInput"}},"pickup_address":{"type":["integer","null"],"description":"Address ID for product pickup (for easy return / refund requests).\nMust be a valid address belonging to the authenticated user.\nOnly required for refund-type cancellations with easy return enabled."},"fully_refund_as_loyalty_money":{"type":"boolean","default":false,"description":"If `true`, the refund amount will be credited as loyalty points\ninstead of being refunded to the original payment method."}}},"OrderItemCancellationInput":{"type":"object","description":"Individual order item cancellation details.","required":["order_item","cancellation_type","reason"],"properties":{"order_item":{"type":"integer","description":"The ID of the order item to cancel."},"cancellation_type":{"type":"string","enum":["cancel","refund"],"description":"Type of cancellation request:\n- `cancel`: Cancel before shipment (no product return needed)\n- `refund`: Return product after delivery (requires easy return process)"},"reason":{"type":"integer","description":"Cancellation reason ID.\nObtain available reasons from the cancellation reasons endpoint."},"description":{"type":["string","null"],"description":"Additional description or notes for the cancellation."},"shipping_company":{"type":["integer","null"],"description":"Easy return shipping company ID.\nRequired only for `refund` type cancellations.\nObtain available companies from the easy return shipping companies endpoint."},"pickup_date":{"oneOf":[{"$ref":"#/components/schemas/PickupDateInput"},{"type":"null"}],"description":"Scheduled pickup date and time range for easy return.\nRequired only for `refund` type cancellations when pickup is needed."},"quantity":{"type":["integer","null"],"minimum":1,"description":"Quantity to cancel (for mergeable/quantity-based order items).\nIf not provided, the entire order item quantity is cancelled.\nCannot exceed the original order item quantity."},"cancellation_request_image_set":{"type":"array","description":"Images related to the cancellation request (e.g., product damage photos).\nLimited by `CANCELLATION_REQUEST_MAX_IMAGE_COUNT_PER_ORDER_ITEM` setting.","items":{"$ref":"#/components/schemas/CancellationRequestImageInput"}}}},"PickupDateInput":{"type":"object","description":"Scheduled pickup date and time range for easy return.","required":["date","hour_range"],"properties":{"date":{"type":"string","format":"date","description":"Pickup date (YYYY-MM-DD format)."},"hour_range":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","description":"Start time of pickup window."},"end":{"type":"string","description":"End time of pickup window."}}}}},"CancellationRequestImageInput":{"type":"object","description":"Image attachment for cancellation request.","required":["image"],"properties":{"image":{"type":"string","format":"byte","description":"Base64 encoded image data."}}}}}}
```

## The OrderItemCancellationInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderItemCancellationInput":{"type":"object","description":"Individual order item cancellation details.","required":["order_item","cancellation_type","reason"],"properties":{"order_item":{"type":"integer","description":"The ID of the order item to cancel."},"cancellation_type":{"type":"string","enum":["cancel","refund"],"description":"Type of cancellation request:\n- `cancel`: Cancel before shipment (no product return needed)\n- `refund`: Return product after delivery (requires easy return process)"},"reason":{"type":"integer","description":"Cancellation reason ID.\nObtain available reasons from the cancellation reasons endpoint."},"description":{"type":["string","null"],"description":"Additional description or notes for the cancellation."},"shipping_company":{"type":["integer","null"],"description":"Easy return shipping company ID.\nRequired only for `refund` type cancellations.\nObtain available companies from the easy return shipping companies endpoint."},"pickup_date":{"oneOf":[{"$ref":"#/components/schemas/PickupDateInput"},{"type":"null"}],"description":"Scheduled pickup date and time range for easy return.\nRequired only for `refund` type cancellations when pickup is needed."},"quantity":{"type":["integer","null"],"minimum":1,"description":"Quantity to cancel (for mergeable/quantity-based order items).\nIf not provided, the entire order item quantity is cancelled.\nCannot exceed the original order item quantity."},"cancellation_request_image_set":{"type":"array","description":"Images related to the cancellation request (e.g., product damage photos).\nLimited by `CANCELLATION_REQUEST_MAX_IMAGE_COUNT_PER_ORDER_ITEM` setting.","items":{"$ref":"#/components/schemas/CancellationRequestImageInput"}}}},"PickupDateInput":{"type":"object","description":"Scheduled pickup date and time range for easy return.","required":["date","hour_range"],"properties":{"date":{"type":"string","format":"date","description":"Pickup date (YYYY-MM-DD format)."},"hour_range":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","description":"Start time of pickup window."},"end":{"type":"string","description":"End time of pickup window."}}}}},"CancellationRequestImageInput":{"type":"object","description":"Image attachment for cancellation request.","required":["image"],"properties":{"image":{"type":"string","format":"byte","description":"Base64 encoded image data."}}}}}}
```

## The PickupDateInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"PickupDateInput":{"type":"object","description":"Scheduled pickup date and time range for easy return.","required":["date","hour_range"],"properties":{"date":{"type":"string","format":"date","description":"Pickup date (YYYY-MM-DD format)."},"hour_range":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","description":"Start time of pickup window."},"end":{"type":"string","description":"End time of pickup window."}}}}}}}}
```

## The CancellationRequestImageInput object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CancellationRequestImageInput":{"type":"object","description":"Image attachment for cancellation request.","required":["image"],"properties":{"image":{"type":"string","format":"byte","description":"Base64 encoded image data."}}}}}}
```

## The OrderAddressChangeRequest object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderAddressChangeRequest":{"type":"object","required":["order","address","order_address_types"],"properties":{"order":{"type":"integer","description":"The ID of the order to update."},"address":{"type":"integer","description":"The ID of the new address from the user's address book."},"order_address_types":{"type":"array","items":{"type":"string","enum":["shipping","billing"]},"description":"Which address types to update (shipping, billing, or both)."},"channel_id":{"type":["integer","null"],"description":"Channel ID (optional, populated automatically)."}}}}}}
```

## The CheckoutProvider object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProvider":{"type":"object","properties":{"pk":{"type":"integer","description":"Provider ID."},"name":{"type":"string","description":"Provider display name."},"slug":{"type":"string","description":"Provider slug identifier."},"logo":{"type":["string","null"],"format":"uri","description":"URL to the provider's logo image."},"is_active":{"type":"boolean","description":"Whether the provider is currently active."}}}}}}
```

## The CheckoutProviderPageResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderPageResponse":{"type":"object","description":"Page context data returned from checkout provider endpoint.\nThe response structure varies depending on which page was processed:\n\n| Page | Response Fields |\n|------|-----------------|\n| `CheckoutProviderIndexPage` | Empty object `{}` |\n| `CheckoutProviderSelectionPage` | `checkout_providers[]`, `redirect_url` (remote payment page) |\n| `CheckoutProviderAddressSelectionPage` | `redirect_url` (to continue on provider) |\n| `CheckoutProviderShippingOptionPage` | `shipping_options[]` |\n| `CheckoutProviderAgreementListPage` | `agreements[]` |\n| `CheckoutProviderNotificationPage` | `return_url`, `merchant_customer_id`, `merchant_customer_date_joined`, `merchant_customer_akifast_date_joined` |\n\nAll fields are optional since different pages return different subsets.","additionalProperties":true,"properties":{"redirect_url":{"type":"string","format":"uri","description":"URL to redirect the user to.\n- **SelectionPage**: Remote payment page URL (e.g., Akifast hosted page).\n- **AddressSelectionPage**: URL to continue checkout on provider page."},"return_url":{"type":"string","format":"uri","description":"**NotificationPage only.**\nURL to redirect after order completion. Points to the order success page."},"merchant_customer_id":{"type":"integer","description":"**NotificationPage only.**\nCustomer's unique ID in the merchant system."},"merchant_customer_date_joined":{"type":"string","format":"date-time","description":"**NotificationPage only.**\nCustomer's registration date in the merchant system."},"merchant_customer_akifast_date_joined":{"type":"string","format":"date-time","description":"**NotificationPage only.**\nDate when customer linked their Akifast account."},"checkout_providers":{"type":"array","description":"**SelectionPage only.**\nList of available checkout providers for this basket.","items":{"type":"object","properties":{"pk":{"type":"integer","description":"Provider ID."},"name":{"type":"string","description":"Provider display name."},"slug":{"type":"string","description":"Provider slug identifier."}}}},"shipping_options":{"type":"array","description":"**ShippingOptionPage only.**\nAvailable shipping options for the delivery address.","items":{"type":"object","properties":{"key":{"type":"integer","description":"Shipping option ID (use this for `shipping_option_key`)."},"name":{"type":"string","description":"Shipping option display name."},"slug":{"type":"string","description":"Shipping option slug."},"logo_url":{"type":"string","format":"uri","description":"URL to the shipping provider's logo."},"shipping_amount":{"type":"string","format":"decimal","description":"Calculated shipping cost for this option."},"description":{"type":"string","description":"Shipping option description (e.g., delivery time)."}}}},"agreements":{"type":"array","description":"**AgreementListPage only.**\nAvailable agreements for user acceptance.","items":{"type":"object","properties":{"code":{"type":"string","description":"Agreement code. Use this in subsequent requests.\nExamples: \"info\", \"sales\""},"text":{"type":"string","description":"Human-readable agreement name."}}}},"code":{"type":"string","description":"**NotificationPage context only.**\nThe selected agreement code."},"text":{"type":"string","description":"**NotificationPage context only.**\nHuman-readable name of the selected agreement."},"agreement_body":{"type":"string","description":"**NotificationPage context only.**\nRendered HTML content of the selected agreement document."}}}}}}
```

## The CheckoutProviderErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CheckoutProviderErrorResponse":{"type":"object","description":"Error response from checkout provider endpoint.\nErrors are returned as field-keyed arrays of error messages.\n\nCommon error keys:\n- `basket`: Basket-related errors (empty, changed, not found)\n- `error`: General processing errors\n- `non_field_errors`: Validation errors not tied to a specific field\n- `conversation_id`: Conversation ID verification failed\n- `agreements`: Agreement acceptance required\n- `is_successful`: Payment success validation\n- `card_info`: Card BIN validation\n- `shipping_option_key`: Shipping option validation","additionalProperties":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object"}}]}}}}}
```

## The CompletedOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CompletedOrderResponse":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/OrderDetail"},"campaigns":{"type":"array","items":{"type":"object"},"description":"Applied campaigns on the order."}}},"OrderDetail":{"type":"object","properties":{"pk":{"type":"integer"},"number":{"type":"string","description":"Order number."},"status":{"$ref":"#/components/schemas/EnumValue"},"currency":{"$ref":"#/components/schemas/EnumValue"},"amount":{"type":"string","format":"decimal"},"discount_amount":{"type":"string","format":"decimal"},"shipping_amount":{"type":"string","format":"decimal"},"shipping_tax_rate":{"type":"string","format":"decimal"},"created_date":{"type":"string","format":"date-time"},"orderitem_set":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemSummary"}},"shipping_address":{"$ref":"#/components/schemas/AddressSummary"},"billing_address":{"$ref":"#/components/schemas/AddressSummary"}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}},"OrderItemSummary":{"type":"object","properties":{"pk":{"type":"integer"},"product":{"$ref":"#/components/schemas/ProductSummary"},"status":{"$ref":"#/components/schemas/EnumValue"},"price":{"type":"string","format":"decimal"},"quantity":{"type":"integer","default":1},"discount_amount":{"type":"string","format":"decimal"},"tracking_number":{"type":["string","null"]},"shipping_company":{"$ref":"#/components/schemas/EnumValue"}}},"ProductSummary":{"type":"object","properties":{"pk":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}}},"AddressSummary":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"line":{"type":"string"},"city":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"country":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}}}}}}}
```

## The TokenCheckoutStatusResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"TokenCheckoutStatusResponse":{"type":"object","properties":{"order_created":{"type":"boolean","description":"Whether an order has been created for the token's basket."},"order_number":{"type":"string","description":"The order number (only present if order_created is true)."}}}}}}
```

## The CancellationRequestResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CancellationRequestResponse":{"type":"object","properties":{"pk":{"type":"integer","description":"Cancellation request ID."},"uuid":{"type":"string","format":"uuid","description":"Unique identifier for the cancellation request."},"order_item":{"type":"integer","description":"Order item ID that is being cancelled."},"status":{"type":"object","description":"Cancellation request status.\n\n**Possible values:**\n- `open`: Request is open and waiting to be processed\n- `waiting`: Waiting for processing\n- `confirmation_waiting`: Waiting for confirmation\n- `confirmed`: Confirmed by the system\n- `waiting_approval`: Waiting for back-office approval\n- `approved`: Approved by the back-office\n- `rejected`: Rejected by the back-office\n- `waiting_for_payment`: Waiting for refund payment\n- `manuel_refund_need`: Requires manual refund processing\n- `completed`: Cancellation completed","properties":{"value":{"type":"string","enum":["open","waiting","confirmation_waiting","confirmed","waiting_approval","approved","rejected","waiting_for_payment","manuel_refund_need","completed"]},"label":{"type":"string","description":"Human-readable status label."}}},"cancellation_type":{"type":"object","description":"Type of cancellation request.\n\n**Possible values:**\n- `cancel`: Order item cancellation (before shipment)\n- `refund`: Refund request (after delivery)","properties":{"value":{"type":"string","enum":["cancel","refund"]},"label":{"type":"string","description":"Human-readable type label."}}},"reason":{"type":"integer","description":"Cancellation reason ID (from CancellationReason model)."},"description":{"type":"string","description":"Additional notes or explanation provided by the customer."},"created_date":{"type":"string","format":"date-time","description":"Date and time when the cancellation request was created."}}}}}}
```

## The OrderAddressChangeResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderAddressChangeResponse":{"type":"object","description":"Response from Omnitron after address change request.","properties":{"status":{"type":"integer","description":"HTTP status code from Omnitron API."}}}}}}
```

## The OrderSummary object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderSummary":{"type":"object","properties":{"number":{"type":"string","description":"Order number."},"amount":{"type":"string","format":"decimal","description":"Total order amount."},"currency":{"$ref":"#/components/schemas/EnumValue"},"status":{"$ref":"#/components/schemas/EnumValue"},"created_date":{"type":"string","format":"date-time"}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}}}}}
```

## The OrderDetail object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderDetail":{"type":"object","properties":{"pk":{"type":"integer"},"number":{"type":"string","description":"Order number."},"status":{"$ref":"#/components/schemas/EnumValue"},"currency":{"$ref":"#/components/schemas/EnumValue"},"amount":{"type":"string","format":"decimal"},"discount_amount":{"type":"string","format":"decimal"},"shipping_amount":{"type":"string","format":"decimal"},"shipping_tax_rate":{"type":"string","format":"decimal"},"created_date":{"type":"string","format":"date-time"},"orderitem_set":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemSummary"}},"shipping_address":{"$ref":"#/components/schemas/AddressSummary"},"billing_address":{"$ref":"#/components/schemas/AddressSummary"}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}},"OrderItemSummary":{"type":"object","properties":{"pk":{"type":"integer"},"product":{"$ref":"#/components/schemas/ProductSummary"},"status":{"$ref":"#/components/schemas/EnumValue"},"price":{"type":"string","format":"decimal"},"quantity":{"type":"integer","default":1},"discount_amount":{"type":"string","format":"decimal"},"tracking_number":{"type":["string","null"]},"shipping_company":{"$ref":"#/components/schemas/EnumValue"}}},"ProductSummary":{"type":"object","properties":{"pk":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}}},"AddressSummary":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"line":{"type":"string"},"city":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"country":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}}}}}}}
```

## The OrderItemSummary object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"OrderItemSummary":{"type":"object","properties":{"pk":{"type":"integer"},"product":{"$ref":"#/components/schemas/ProductSummary"},"status":{"$ref":"#/components/schemas/EnumValue"},"price":{"type":"string","format":"decimal"},"quantity":{"type":"integer","default":1},"discount_amount":{"type":"string","format":"decimal"},"tracking_number":{"type":["string","null"]},"shipping_company":{"$ref":"#/components/schemas/EnumValue"}}},"ProductSummary":{"type":"object","properties":{"pk":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}}}}}
```

## The ProductSummary object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"ProductSummary":{"type":"object","properties":{"pk":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}}}}}}
```

## The AddressSummary object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"AddressSummary":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"line":{"type":"string"},"city":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"country":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}}}}}}}
```

## The EnumValue object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}}}}}
```

## The ValidationErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}
```