openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Orders API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
tags:
- name: Orders
description: 'An Order is created through the [checkout](/docs/api/carts/checkout) endpoint within the Carts API.
An order is created after a customer checks out their cart. On creation, the order is marked unpaid. The customer is prompted for a shipping address, a billing address, and a payment method. After the order is successfully paid, you can trigger an inventory process and a shipping process.
You can keep a history of orders associated with the customer account.
### Reorder
A re-order is when a shopper copies items from a previous order from their order history into a cart of their choice. If a shopper re-orders to an empty cart, the same quantities as the past order are applied. If the shopper re-orders to an existing cart, and orders the same item, the quantity increases. If an item is out of stock, the item is not added to the cart, and the shopper sees an insufficient stock error. The tax for the items in a re-order is not applied. For more information, see [Tax Items](/docs/api/carts/tax-items).
'
paths:
/v2/orders:
parameters: []
get:
tags:
- Orders
summary: Get all Orders
description: 'This endpoint returns all orders with custom flow fields. The pagination offset is set to fetch a maximum of 10,000 orders. If the store has 10,000 orders, and you fetch the orders without using filters, an error is returned. Use a filter to view orders when the order is beyond the 10,000 mark.
:::note
- Pass the `X-Moltin-Customer-Token` header to limit orders to a specific customer. See [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens).
- Pass the `EP-Account-Management-Authentication-Token` header to limit orders to a specific account. See [Account Management Token](/docs/api/accounts/post-v-2-account-members-tokens).
- You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).
:::
### Filtering
The following operators and attributes are available for filtering orders.
| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `status` | `string` | `eq` | `eq(status,complete)` |
| `payment` | `string` | `eq` | `eq(payment,paid)` |
| `shipping` | `string` | `eq` | `eq(shipping,unfulfilled)` |
| `name` (`customer.name`) | `string` | `eq` / `like` | `like(name,Brad*)` |
| `email` (`customer.email`) | `string` | `eq` / `like` | `like(email,*@elasticpath.com)` |
| `customer_id` | `string` | `eq` / `like` | `eq(customer_id, e5a0d684-a4af-4919-a348-f66b0b4955e0)` |
| `account_id` | `string` | `eq` / `like` | `eq(account_id,3d7200c9-a9bc-4085-9822-63e80fd94a09)` |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,2a8a3a92-2ccd-4b2b-a7af-52d3896eaecb)` |
| `contact.name` | `string` | `eq` / `like` | `eq(name,John Doe)` |
| `contact.email` | `string` | `eq` / `like` | `eq(email,John Doe)` |
| `shipping_postcode` | `string` | `eq` / `like` | `like(shipping_postcode,117*)` |
| `billing_postcode` | `string` | `eq` / `like` | `like(billing_postcode,117*)` |
| `with_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(with_tax,10000)` |
| `without_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(without_tax,10000)` |
| `currency` | `string` | `eq` | `eq(currency,USD)` |
| `product_id` | `string` | `eq` | `eq(product_id,6837058c-ae42-46db-b3c6-7f01e0c34b40)` |
| `product_sku` | `string` | `eq` | `eq(product_sku,deck-shoe-001)` |
| `created_at` | `date` | `eq` / `gt` / `ge`/ `le` / `lt` | `gt(created_at,YYYY-MM-DD)` |
| `updated_at` | `date` | `eq` / `gt` / `ge`/ `le`/ `lt` | `lt(updated_at,YYYY-MM-DD)` |
| `external_ref` | `string` | `eq` / `like` | `like(external_ref, 16be*)` |
| `order_number` | `string` | `eq` / `like` | `like(order_number, 123*)` |
### Includes
You can include related resources with the order response by using the `include` query parameter.
| Name | Optional | Type | Description | |:-----|:---------|:-----|:------------| | `include` | Optional | `string` | Comma-delimited string of entities that can be included. The information included are `items`, `tax_items`, `custom_discounts`, or `promotions`. |
'
operationId: getCustomerOrders
parameters:
- name: x-moltin-customer-token
in: header
description: A customer token to access a specific customer's orders.
style: simple
schema:
type: string
examples:
- '{{customerToken}}'
- name: include
in: query
description: Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- items
- items,tax_items
- items,tax_items,custom_discounts
- name: page[limit]
in: query
description: The maximum number of records per page.
required: false
style: form
explode: true
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: page[offset]
in: query
description: The number of records to offset the results by.
required: false
style: form
explode: true
schema:
type: integer
minimum: 0
maximum: 10000
default: 0
- name: filter
in: query
description: Filter expression for searching orders. See filtering documentation for available operators and attributes.
required: false
style: form
explode: false
schema:
type: string
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCollectionResponse'
deprecated: false
/v2/orders/{orderID}:
parameters: []
get:
tags:
- Orders
summary: Get an Order
description: 'Use this endpoint to retrieve a specific order.
### Includes
You can include related resources with the order response by using the `include` query parameter.
| Name | Required | Type | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `items`, `tax_items`, `custom_discounts`, or `promotions`. |'
operationId: getAnOrder
parameters:
- name: orderID
in: path
description: The ID of the order.
required: true
style: simple
schema:
type: string
- name: include
in: query
description: Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- items
- items,tax_items
- items,tax_items,custom_discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEntityResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Order not found
value: "{\n \"errors\": [\n {\n \"detail\": \"Order not found\",\n \"status\": \"404\",\n \"title\": \"Not Found\"\n }\n ]\n}\n"
deprecated: false
put:
tags:
- Orders
summary: Update an Order
description: "You can only update custom data, `shipping`, `shipping_address`, and status of orders. All other settings in the order object are immutable.\n\n This endpoint allows you to:\n\n- **Update an order number and external reference**: You can update an existing order that does not have an `order_number` and `external_ref`, modify the `order_number` and `external_ref` values, or remove them by passing an empty value in the `order_number` and `external_ref` fields.\n- **Cancel an order**: You can cancel an order only if it has not been fulfilled.\n- **Fulfill an order**: You can fulfill a paid order only.\n\n:::caution\n\nYou can update `shipping`, `shipping_address`, and status of an order only if the order is not fulfilled. You can use the refund API to refund an order only if the payment status is `paid`. Canceling an order does not automatically refund a payment. You must refund the orders manually.\n\n:::\n\n:::note\n\n- This request is only accessible to client credentials token users with Seller Admin role.\n- Non client credentials token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions).\n- The `order_number` will appear as the invoice number in Authorize.net transactions.\n\n:::\n"
operationId: updateAnOrder
parameters:
- name: orderID
in: path
description: The unique identifier of the order.
required: true
style: simple
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrdersUpdateRequest'
examples:
CancelAnOrder:
summary: Cancel an Order
value:
data:
type: order
status: cancelled
FulfillAnOrder:
summary: Fulfill an Order by ID. You can fulfill a paid order only.
value:
data:
type: order
shipping: fulfilled
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Bad Request
value: "{\n \"errors\": [\n {\n \"detail\": \"Request could not be processed\",\n \"status\": \"400\",\n \"title\": \"Bad Request\"\n }\n ]\n}\n"
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Validation error
value: "{\n \"errors\": [\n {\n \"detail\": \"Order cannot be updated in its current state\",\n \"status\": \"422\",\n \"title\": \"Unprocessable Entity\"\n }\n ]\n}\n"
deprecated: false
/v2/orders/{orderID}/items:
parameters: []
get:
tags:
- Orders
summary: Get Order Items
description: 'Use this endpoint to retrieve order items.
### Includes
You can include related resources with the order items response by using the `include` query parameter.
| Name | Required | Type | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `tax_items`, `custom_discounts`, or `promotions`. |'
operationId: getOrderItems
parameters:
- name: orderID
in: path
description: The ID of the order.
required: true
style: simple
schema:
type: string
- name: include
in: query
description: Comma-delimited string of entities to include (tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- tax_items
- tax_items,custom_discounts
- tax_items,custom_discounts,promotions
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/OrderItemCollectionResponse'
deprecated: false
/v2/orders/anonymize:
parameters: []
post:
tags:
- Orders
summary: Anonymize Orders
description: 'You can anonymize an order when it is fulfilled, canceled, or fully refunded.
When anonymization is successful, Personal Identifiable Information such as customer details, `shipping_address`, and `billing_address` are replaced with *.
'
operationId: anonymizeOrders
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrdersAnonymizeRequest'
- examples:
- data:
order_ids:
- '{{orderID}}'
contentMediaType: application/json
examples:
default:
value:
data:
order_ids:
- '{{orderID}}'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersListResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
example:
errors:
- detail: 'Order has status: order:incomplete, payment:unpaid, shipping:unfulfilled; only fulfilled or refunded or cancelled orders may be anonymized'
status: 422
title: Could not anonymize orders
meta:
order_id: 496c29a1-6e7a-4ab6-a4e7-d1ec9a08b85e
deprecated: false
/v2/orders/{orderID}/confirm:
parameters: []
post:
tags:
- Orders
summary: Confirm Order
description: 'Use this endpoint to confirm an order. Confirming an order finalizes it and makes it ready for processing.
'
operationId: confirmOrder
parameters:
- name: orderID
in: path
description: The unique identifier of the order to confirm.
required: true
style: simple
schema:
type: string
responses:
'200':
description: Order confirmed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Required field missing
value: "{\n \"errors\": [\n {\n \"detail\": \"Request could not be processed\",\n \"status\": \"400\",\n \"title\": \"Bad Request\"\n }\n ]\n}\n"
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Order not found
value: "{\n \"errors\": [\n {\n \"detail\": \"Order not found\",\n \"status\": \"404\",\n \"title\": \"Not Found\"\n }\n ]\n}\n"
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Validation error
value: "{\n \"errors\": [\n {\n \"detail\": \"Order cannot be confirmed in its current state\",\n \"status\": \"422\",\n \"title\": \"Unprocessable Entity\"\n }\n ]\n}\n"
components:
schemas:
OrderTimestamps:
type: object
properties:
created_at:
description: The date this order was created.
type: string
updated_at:
description: The date this order was last updated.
type: string
fully_paid_at:
description: The date this order was fully paid. Only present for orders with payment status 'paid'.
type: string
CustomDiscountResponse:
title: CustomDiscountResponse
type: object
properties:
type:
description: Specifies the type of the resource. Always `custom_discount`.
type: string
const: custom_discount
id:
description: Specifies the UUID of the custom discount.
type: string
format: uuid
examples:
- 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9
external_id:
description: Specifies an external id for the custom discount.
type: string
examples:
- custom-discount-external-id
discount_engine:
description: 'Specifies from where the custom discount is applied.
'
type: string
examples:
- Custom Discount Engine
amount:
description: The amount of the custom discount.
$ref: '#/components/schemas/FormattedPriceData'
description:
description: Specifies a description for the custom discount.
type: string
examples:
- Custom discount description
discount_code:
description: Specifies the discount code used for the custom discount.
type: string
examples:
- cart-custom-promo-code
relationships:
description: Relationships to other resources like cart items
type: object
properties:
item:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
description: The cart item ID this discount is related to
type:
type: string
enum:
- cart_item
- custom_item
OrderItemResponse:
title: OrderItemResponse
type: object
properties:
type:
description: The type represents the object being returned.
type: string
examples:
- order_item
id:
description: The unique identifier for this order item.
type: string
format: uuid
readOnly: true
examples:
- 68bf8510-bebf-47b1-96ba-8a9930c7d928
quantity:
description: The quantity of this item were ordered.
type: number
examples:
- 1
product_id:
description: The unique identifier for this order item.
type: string
format: uuid
readOnly: true
examples:
- 4e9c6098-9701-4839-a69c-54d8256d9012
subscription_offering_id:
description: The unique identifier for the subscription offering for this order item.
type: string
format: uuid
readOnly: true
examples:
- 69a39623-e681-415e-83c0-e1281010c77d
name:
description: The name of this order item.
type: string
examples:
- Product 123
sku:
description: The SKU code for the order item.
type: string
examples:
- IFD-1
location:
description: The stock location for this order item.
type: string
readOnly: true
unit_price:
$ref: '#/components/schemas/OrderPriceData'
value:
$ref: '#/components/schemas/OrderPriceData'
discounts:
type: array
items:
$ref: '#/components/schemas/DiscountData'
links:
type: object
meta:
type: object
properties:
display_price:
type: object
properties:
with_tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
without_tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
discount:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
without_discount:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
discounts:
type: object
additionalProperties:
type: object
properties:
amount:
type: number
examples:
- -1000
currency:
type: string
examples:
- USD
formatted:
type: string
examples:
- -$1.00
constituents:
type: object
description: Detailed breakdown of discount constituents by ID
additionalProperties:
type: object
properties:
amount:
type: number
description: The discount amount
currency:
type: string
description: The currency code
formatted:
type: string
description: The formatted discount amount
original_price:
description: The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product).
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
timestamps:
$ref: '#/components/schemas/Timestamps'
relationships:
type: object
properties:
cart_item:
type: object
properties:
data:
type: object
properties:
type:
description: The type represents the object being returned.
type: string
examples:
- order_item
id:
description: The unique identifier for this item.
type: string
format: uuid
readOnly: true
examples:
- 5601a4b1-9d13-42d3-8fb7-03b35169d1b6
taxes:
description: Related tax items.
type: object
properties:
data:
oneOf:
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/RelationshipItem'
promotions:
description: Related promotions.
type: object
properties:
data:
oneOf:
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/RelationshipItem'
catalog_id:
description: The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.
type: string
examples:
- default
catalog_source:
description: The catalog source. Always `pim` or `legacy`.
type: string
examples:
- pim
- legacy
bundle_configuration:
description: Configuration for bundle products.
type: object
properties:
selected_options:
type: object
additionalProperties:
type: object
additionalProperties:
type: number
component_products:
description: Array of component products for bundle configuration
type: array
items:
type: object
properties:
id:
description: Component product ID
type: string
type:
description: Component product type
type: string
attributes:
description: Product attributes as a generic object
type: object
additionalProperties: true
meta:
description: Product metadata as a generic object
type: object
additionalProperties: true
price:
description: Product price information as a generic object
type: object
additionalProperties: true
relationships:
description: Product relationships as a generic object
type: object
additionalProperties: true
components:
description: Components of the bundle product.
type: object
additionalProperties:
type: object
properties:
name:
type: string
options:
type: array
items:
type: object
properties:
id:
type: string
quantity:
type: number
type:
type: string
custom_inputs:
description: Custom inputs for the order item as a generic object
type: object
additionalProperties: true
custom_attributes:
description: Custom attributes attached to the order item.
readOnly: true
$ref: '#/components/schemas/CustomAttributes'
shipping_group_id:
description: The shipping group ID for the order item
type: string
promotion_source:
description: The promotion source for the order item
type: string
subscription_configuration:
description: Subscription configuration for the order item
type: object
properties:
plan:
description: Subscription plan details
type: string
pricing_option:
description: Pricing option for the subscription
type: string
DiscountFormattedPriceData:
title: DiscountFormattedPriceData
type: object
properties:
amount:
description: The discount amount. Must be non-positive (zero or negative).
type: number
maximum: 0
examples:
- -1000
- 0
currency:
description: The currency set for this amount.
type: string
examples:
- USD
formatted:
description: The formatted total based on the amount and currency.
type: string
examples:
- -$10.00
- $0.00
FormattedPriceData:
title: FormattedPriceData
type: object
properties:
amount:
description: The raw total.
type: number
examples:
- 10000
currency:
description: The currency set for this amount.
type: string
examples:
- USD
formatted:
description: The formatted total based on the amount and currency.
type: string
examples:
- $10.00
Timestamps:
type: object
properties:
created_at:
description: The date this was created.
type: string
updated_at:
description: The date this was last updated.
type: string
Response.ErrorItem:
type: object
required:
- status
- title
properties:
title:
type: string
description: A brief summary of the error.
examples:
- Bad Request
status:
type:
- string
- integer
description: The HTTP response code of the error.
examples:
- '400'
detail:
type: string
description: Optional additional detail about the error.
examples:
- The field 'name' is required
source:
type: string
description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity').
meta:
type: object
description: Additional metadata associated with the error. May include arbitrary keys.
properties:
id:
type: string
description: The resource id associated with the error
ids:
type: array
items:
type: string
description: The resource ids associated with the error
item_ids:
type: array
items:
type: string
description: The cart_item ids associated with the error
shipping_group_id:
type: string
description: The shipping group id associated with the error
shipping_group_ids:
type: array
items:
type: string
description: The shipping group ids associated with the error
cart_id:
type: string
description: The cart id associated with the error
code:
type: string
description: The code associated with the error.
order_id:
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-orders-api-openapi.yml