# 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"}}}}}} ``` ## The IVRPreOrderRequest object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVRPreOrderRequest":{"type":"object","required":["username","password","orderNumber"],"properties":{"username":{"type":"string","description":"IVR integration username."},"password":{"type":"string","description":"IVR integration password."},"orderNumber":{"type":"string","description":"The order number for which to retrieve pre-order details."}}}}}} ``` ## The IVRPreOrderResponse object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVRPreOrderResponse":{"type":"object","description":"Returned for both successful and failed IVR pre-order lookups.\nCheck `result.success` to determine the outcome.","properties":{"result":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if the pre-order was found and is valid; `false` on failure."},"errortext":{"type":"string","description":"Human-readable error description. Empty string on success."}}},"productlist":{"type":"array","description":"List of products in the basket. Empty array on failure.","items":{"$ref":"#/components/schemas/IVRProductListItem"}},"orderprice":{"type":"number","description":"Total order price including discounts. `0.0` on failure."}}},"IVRProductListItem":{"type":"object","description":"Summary of a basket item as presented to the IVR system.","properties":{"productnumber":{"type":"string","description":"Product SKU code."},"discountedprice":{"type":"number","description":"Item total after applying any discounts."},"realprice":{"type":"number","description":"Item total before discounts."},"quantity":{"type":"integer","description":"Quantity of this product in the basket."},"productname":{"type":"string","description":"Display name of the product."}}}}}} ``` ## The IVRProductListItem object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVRProductListItem":{"type":"object","description":"Summary of a basket item as presented to the IVR system.","properties":{"productnumber":{"type":"string","description":"Product SKU code."},"discountedprice":{"type":"number","description":"Item total after applying any discounts."},"realprice":{"type":"number","description":"Item total before discounts."},"quantity":{"type":"integer","description":"Quantity of this product in the basket."},"productname":{"type":"string","description":"Display name of the product."}}}}}} ``` ## The IVRCompleteRequest object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVRCompleteRequest":{"type":"object","required":["username","password","orderResultRequest"],"properties":{"username":{"type":"string","description":"IVR integration username."},"password":{"type":"string","description":"IVR integration password."},"orderResultRequest":{"$ref":"#/components/schemas/IVROrderResultRequest"}}},"IVROrderResultRequest":{"type":"object","required":["orderNumber","referenceNumber","staffId"],"properties":{"orderNumber":{"type":"string","description":"The order number associated with the pre-order session."},"referenceNumber":{"type":"string","description":"Unique payment reference number assigned by the IVR system. Used as the transaction identifier."},"staffId":{"type":"string","description":"Identifier of the staff member who processed the payment."},"success":{"type":"boolean","default":true,"description":"Payment success indicator. Must be `true` for the request to be accepted."}}}}}} ``` ## The IVROrderResultRequest object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVROrderResultRequest":{"type":"object","required":["orderNumber","referenceNumber","staffId"],"properties":{"orderNumber":{"type":"string","description":"The order number associated with the pre-order session."},"referenceNumber":{"type":"string","description":"Unique payment reference number assigned by the IVR system. Used as the transaction identifier."},"staffId":{"type":"string","description":"Identifier of the staff member who processed the payment."},"success":{"type":"boolean","default":true,"description":"Payment success indicator. Must be `true` for the request to be accepted."}}}}}} ``` ## The IVRCompleteResponse object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"IVRCompleteResponse":{"type":"object","description":"Returned for both successful and failed IVR payment result submissions.\nCheck `orderResultResponse.result.success` to determine the outcome.","properties":{"orderResultResponse":{"type":"object","properties":{"result":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if the payment result was accepted; `false` on failure."},"errortext":{"type":"string","description":"Human-readable error description. Empty string on success."}}}}}}}}}} ``` ## The CashRegisterPreOrderRequest object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterPreOrderRequest":{"type":"object","required":["order_number","username","password"],"properties":{"order_number":{"type":"string","description":"Order number previously generated by the `get_order_number` endpoint."},"username":{"type":"string","description":"Integration username for authenticating the cash register request."},"password":{"type":"string","description":"Integration password for authenticating the cash register request."}}}}}} ``` ## The CashRegisterPreOrderResponse object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterPreOrderResponse":{"type":"object","description":"On success, contains `order_number` and `pre_order` (plus optional `card`).\nOn failure, contains `error_code` and `error_message`.","properties":{"order_number":{"type":"string","description":"The order number from the request. Present on success only."},"pre_order":{"type":"object","description":"Full pre-order details including basket contents, addresses, payment and shipping options,\namounts, and additional data stored on the pre-order.","additionalProperties":true,"properties":{"basket":{"type":"object","description":"The basket associated with this pre-order.","additionalProperties":true},"shipping_address":{"type":"object","description":"Selected shipping address. Null if not yet set.","nullable":true},"billing_address":{"type":"object","description":"Selected billing address. Null if not yet set.","nullable":true},"payment_option":{"type":"object","description":"Selected payment option. Null if not yet set.","nullable":true},"shipping_option":{"type":"object","description":"Selected shipping option. Null if not yet set.","nullable":true},"shipping_amount":{"type":"string","format":"decimal","description":"Calculated shipping cost.","nullable":true},"total_amount":{"type":"string","format":"decimal","description":"Total order amount including shipping.","nullable":true},"unpaid_amount":{"type":"string","format":"decimal","description":"Outstanding amount to be paid.","nullable":true},"currency_type_label":{"type":"string","description":"Human-readable currency label."}}},"card":{"type":"object","description":"Present only when installment payments are enabled for the cash register integration\nand an installment plan is selected on the pre-order.","properties":{"card_payment_type":{"type":"string","description":"Type of card payment (e.g., credit, debit)."},"name":{"type":"string","description":"Card product name."},"slug":{"type":"string","description":"Card slug identifier."},"bank":{"type":"object","properties":{"name":{"type":"string","description":"Issuing bank name."},"slug":{"type":"string","description":"Issuing bank slug."}}}}},"error_code":{"type":"string","description":"Error code when the request fails. Not present on success."},"error_message":{"type":"string","description":"Human-readable error description. Not present on success."}}}}}} ``` ## The CashRegisterOrderNumberResponse object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterOrderNumberResponse":{"type":"object","description":"Response from the order number generation endpoint.\nOn success, only `order_number` is present.\nOn failure, `error_code` and `error_message` are present; `order_number` may or may not be included.","properties":{"order_number":{"type":"string","description":"Generated unique order number. Present on success and on error_code 408."},"error_code":{"type":"string","description":"Error code when the pre-order state is invalid.\n- `\"407\"`: No payment option set.\n- `\"408\"`: Payment option is not cash register type."},"error_message":{"type":"string","description":"Human-readable error description. Only present on failure."}}}}}} ``` ## The CashRegisterCompleteRequest object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterCompleteRequest":{"type":"object","required":["transaction_id","order_number","username","password","amount"],"properties":{"transaction_id":{"type":"string","description":"Unique transaction identifier assigned by the cash register terminal."},"order_number":{"type":"string","description":"The order number associated with the active pre-order session."},"username":{"type":"string","description":"Integration username for authenticating the cash register request."},"password":{"type":"string","description":"Integration password for authenticating the cash register request."},"amount":{"type":"string","format":"decimal","description":"Total amount to be paid. Must match the outstanding balance on the pre-order.\nUsed for validation unless `promotions` are provided, in which case\n`discounted_amount` is used instead."},"discounted_amount":{"type":"string","format":"decimal","description":"Discounted total after promotions are applied. Required when `promotions` is provided.\nUsed for balance validation instead of `amount`."},"terminal_code":{"type":"string","description":"Identifier of the cash register terminal. Optional."},"promotions":{"type":"array","description":"Promotions to apply to the basket before completing the payment.\nWhen provided, `discounted_amount` is used for amount validation.","items":{"$ref":"#/components/schemas/CashRegisterPromotion"}}}},"CashRegisterPromotion":{"type":"object","required":["benefit_amount"],"properties":{"benefit_amount":{"type":"string","format":"decimal","description":"Discount amount to apply."},"description":{"type":"string","maxLength":512,"description":"Description of the promotion. Defaults to \"Cash Register Offer\" if not provided."},"affected_basket_items":{"type":"array","description":"IDs of basket items to which this promotion applies. Defaults to all items if empty.","items":{"type":"integer"}}}}}}} ``` ## The CashRegisterPromotion object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterPromotion":{"type":"object","required":["benefit_amount"],"properties":{"benefit_amount":{"type":"string","format":"decimal","description":"Discount amount to apply."},"description":{"type":"string","maxLength":512,"description":"Description of the promotion. Defaults to \"Cash Register Offer\" if not provided."},"affected_basket_items":{"type":"array","description":"IDs of basket items to which this promotion applies. Defaults to all items if empty.","items":{"type":"integer"}}}}}}} ``` ## The CashRegisterCompleteResponse object ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"components":{"schemas":{"CashRegisterCompleteResponse":{"type":"object","description":"Returned for both successful and failed cash register payment completions.\nThe `result` field indicates the outcome.","properties":{"transaction_id":{"type":["string","null"],"description":"Transaction identifier from the request. `null` on failure."},"order_number":{"type":["string","null"],"description":"Order number from the request. `null` when the order was not resolved."},"result":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"`\"0\"` on success. Integer error code on failure:\n402 (invalid input or basket changed), 403 (invalid credentials),\n404 (order not found), 405 (amount mismatch), 407 (payment option not set),\n408 (wrong payment option type), 411 (pre-order not found), 412 (offer application error)."},"error_message":{"type":"string","description":"Human-readable error description. Empty string on success."},"amount":{"type":["string","null"],"format":"decimal","description":"Confirmed payment amount. `null` on failure."},"staff_id":{"type":["integer","null"],"description":"Staff member identifier from the pre-order. `null` on failure."},"staff_email":{"type":["string","null"],"description":"Email of the staff member associated with the pre-order. `null` on failure."},"store_id":{"type":["string","null"],"description":"Store identifier from the pre-order. `null` on failure."},"shipping_sku":{"type":["string","null"],"description":"SKU of the configured shipping product for cash register payments.\n`null` if not configured or on failure."}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/orders/models.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.