Requires
orderaccess scope. For more info , refer to:access scope
Order API
The Order APIs enable developers to manage orders in authenticated stores. These APIs provide tools for handling order creation, updates, refunds, and risk assessments.
Available APIs:
Order: Manage orders within the store. An order contains all the information related to a single purchase, including following objects. These APIs also allow merchants to retrieve order lists, update order details, and handle order payments and cancellations.:
- Customer Information
- Line Items (products purchased)
- Shipping Address
- Billing Address
Order Risk : Manage order risk to help merchants identify and mitigate potential risks associated with specific transactions. This includes creating, retrieving, updating, and deleting risk-related information for orders.
Refund:Manage refunds related to orders. These APIs help merchants process and track refunds, ensuring efficient handling of post-sale customer requests. Key features include:
- Retrieving refund lists and their details.
- Processing full or partial refunds for an order.Noted:
All date time related parameters require ISO-8601 format in UTC time zone.
Object Model
Order
Order: The Order object represents a comprehensive record of a customer’s purchase on the platform. It contains detailed information about the transaction, including pricing, customer data, and fulfillment details. Here’s a clear explanation of its components without using a table:
LineItem: The LineItem object represents individual products or product variants within an order. Each LineItem corresponds to a specific product (or product variant) that a customer has purchased. It provides detailed information about the product, its pricing, shipping requirements, and customization options. This object is critical for tracking product-level details within the broader context of an order.
The LineItem object is tightly coupled with the Order object. An Order consists of one or more LineItems, which represent the individual products or product variants purchased in the order. The relationship between these two objects is a 1-to-N relationship.
PaymentLine: The PaymentLine object represents the details of one payment transaction associated with an order. It provides information about the payment method, channel, transaction identifiers, and the total amount paid.
PaymentLines: The payment_lines is an array of multiple payment methods used for an order. It is designed for orders where multiple payment methods are involved, such as when a customer uses a gift card and a third-party payment method (e.g., PayPal) to pay for a single order.
Fulfillment:The Fulfillment Object represents the shipment process for that order and tracks its current status, such as initialled (order unpaid), waiting (awaiting shipment), shipped (fully shipped), or finished (fully received). The object provides crucial metadata like creation and update timestamps, allowing for time-based tracking of the shipment.
Customer:The Customer Object represents a user linked to a store, maintaining a one-to-one relationship with an order. It includes identifiers like id, email, and name, tracks activity through timestamps (created_at, updated_at), manages marketing preferences (subscribed, sms_subscribed_flag), and links to a store (store_id) and address (location_id). Additional fields like tags and note support personalization and detailed customer management.
ShippingAddress:The Shipping Address Object represents the consignee’s delivery details and maintains a one-to-one relationship with an order (shipping address:order = 1:1). It includes fields such as name, first_name, last_name, and gender for consignee identification. The default field indicates if the address is the default for the customer. Nested under extra_info, fields like cpf (tax ID), id_number, and id_number_text provide extended identification information. This object ensures precise and complete delivery details for an order.
BillingAddress:The Billing Address Object represents the consignee’s billing address details and maintains a one-to-one relationship with an order (billing address:order = 1:1). It includes fields such as name, first_name, last_name, and gender for consignee identification. The default field indicates if the address is the default for the customer. Nested under extra_info, fields like cpf (tax ID), id_number, and id_number_text provide extended identification information. This object ensures precise and complete billing address details for an order.
LocationLine: The LocationLine Object represents a specific location of merchant‘s store, shop, or warehouse.
OrderConfig: The OrderConfig Object defines the configuration settings for an order and maintains a one-to-one relationship with it (OrderConfig:order = 1:1). Key fields include pay_type for specifying the payment method, product_tax_included to indicate if taxes are included in the product price, and requires_shipping to determine if shipping is required. It also includes checkout_business_type and checkout_template_type to customize the checkout process. The market_setting field contains additional market-specific configurations, ensuring precise control over order handling and processing.
MarketSetting: The MarketSetting Object defines the market-specific configurations for an order and maintains a one-to-one relationship with the OrderConfig Object (MarketSetting:OrderConfig = 1:1).
MarketCurrencySymbol: The MarketCurrencySymbol Object defines the currency formatting and symbols for a market. It includes the code field for the currency code (e.g., USD) and the val field for the currency symbol (e.g., $). The left field specifies content (e.g., $) displayed to the left of the number, while the right field specifies content displayed to the right. This object ensures proper representation and localization of currency formats in market configurations.
MarketPriceSetting:The MarketPriceSetting Object defines pricing and exchange rate configurations for a market, including whether local currency is enabled (local_currency_enabled) and if a custom rate is active (custom_rate_enabled).
Order Status
| Status | desc |
|---|---|
| opened | Order successfully created |
| canceled | Cancellation of unpaid order |
| placed | Completed paid orders |
| finished | The scenarios where the order is in the finished state:1. All items in the order have been received 2. Order cancelled after payment 3. Full refund of order amount with all items deleted 4. Full refund of order amount with all items returned |
Financial Status
| Status | Desc |
|---|---|
| waiting | Pending payment |
| paying | Payment Processing |
| authorized | Authorized |
| partially_paid | Partial Payment (Gift Card Used) |
| paid | Payment Received |
| cancelled | Payment Cancelled |
| failed | Payment Failed |
| refunding | Refund Processing |
| refund_fail | Refund Failed |
| refunded | Fully Refunded |
| partially_refunded | Partial Refund |
Fulfillment Status
| Status | Desc |
|---|---|
| initialled | Initial status, order unpaid |
| waiting | Awaiting shipment |
| cancelled | Cancel shipment |
| partially_shipped | Partial shipment |
| shipped | Full shipment |
| partially_finished | Partial receipt |
| finished | Full receipt |
| returning | Return in progress |
| partially_returned | Partial return |
| returned | Full return |
Refund
RefundLineItem:The RefundLineItem represents the individual items(products) being refunded within a refund request. It links back to specific order and tracks the details for the individual products being refunded, including quantities, taxes, discounts, and totals.
LineItem:The LineItem represents the original purchase details for a specific product in the order. Each RefundLineItem is directly linked to a LineItem from the original order.
PaymentDetail: A Refund can be processed through multiple PaymentDetails, especially if the original order was paid using multiple payment methods or channels. Each PaymentDetail specifies the refund amount processed through a specific payment method or channel.