openapi: 3.0.3 info: title: Omnivore Order API description: API for managing marketplace orders in the Omnivore platform version: 2.0.0 contact: name: Omnivore Support url: https://omnivore.com.au servers: - url: https://m2.omnivore.com.au/v2 description: Production server security: - clientCredentials: [] paths: /retailer/{retailer_code}/marketplace/{marketplace_code}/order/create: post: summary: Create Order description: | Creates a new order for the specified retailer and marketplace. The combination of `marketplace_code` and `order_number` uniquely identifies the order. operationId: createOrder tags: - Orders parameters: - $ref: '#/components/parameters/RetailerCode' - $ref: '#/components/parameters/MarketplaceCode' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Order' responses: '200': description: Order created successfully content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Invalid request data content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' /retailer/{retailer_code}/marketplace/{marketplace_code}/order/view: get: summary: View Order description: Retrieves a single order by order number for the specified retailer and marketplace. operationId: viewOrder tags: - Orders parameters: - $ref: '#/components/parameters/RetailerCode' - $ref: '#/components/parameters/MarketplaceCode' - name: order_number in: query description: The order number as assigned by the marketplace required: true schema: type: string maxLength: 255 example: "1234567890123-1234567890123" responses: '200': description: Order retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Order' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/Error' /retailer/{retailer_code}/orders/list: get: summary: List Orders description: Returns a paginated list of orders for the specified retailer across all marketplaces. operationId: listOrders tags: - Orders parameters: - $ref: '#/components/parameters/RetailerCode' - $ref: '#/components/parameters/ListMax' - $ref: '#/components/parameters/ListOffset' - $ref: '#/components/parameters/ListOrderNumber' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListSort' - $ref: '#/components/parameters/ListOrder' - $ref: '#/components/parameters/ListCreatedAfter' - $ref: '#/components/parameters/ListCreatedBefore' - $ref: '#/components/parameters/ListUpdatedAfter' - $ref: '#/components/parameters/ListUpdatedBefore' - $ref: '#/components/parameters/ListCreatedInMarketplaceAfter' - $ref: '#/components/parameters/ListCreatedInMarketplaceBefore' responses: '200': description: Order list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/OrderListResponse' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' /retailer/{retailer_code}/marketplace/{marketplace_code}/orders/list: get: summary: List Orders for a Marketplace description: Returns a paginated list of orders filtered to a specific marketplace. operationId: listMarketplaceOrders tags: - Orders parameters: - $ref: '#/components/parameters/RetailerCode' - $ref: '#/components/parameters/MarketplaceCode' - $ref: '#/components/parameters/ListMax' - $ref: '#/components/parameters/ListOffset' - $ref: '#/components/parameters/ListOrderNumber' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListSort' - $ref: '#/components/parameters/ListOrder' - $ref: '#/components/parameters/ListCreatedAfter' - $ref: '#/components/parameters/ListCreatedBefore' - $ref: '#/components/parameters/ListUpdatedAfter' - $ref: '#/components/parameters/ListUpdatedBefore' - $ref: '#/components/parameters/ListCreatedInMarketplaceAfter' - $ref: '#/components/parameters/ListCreatedInMarketplaceBefore' responses: '200': description: Order list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/OrderListResponse' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' /retailer/{retailer_code}/marketplace/{marketplace_code}/order/update: post: summary: Update Order description: | Updates an order's status and/or shipping information. Supports multiple update scenarios via the `status` field: - **Acknowledge** (`pending-shipped`): Confirm receipt of the order into the retailer's system. Optionally supply `retailer_order_id` and `retailer_order_number` to link to the retailer's own system. - **Ship** (`shipped`): Provide `shipping.carrier` and `shipping.tracking_code`. If no `line_items` are specified the entire order is marked as shipped. - **Partial shipment** (`shipped`): Supply `line_items` with `quantityShipped` to ship a subset of items. The order is fully shipped once all items are marked. - **Cancel** (`retailer-cancellation`): Cancels the order in the marketplace and triggers a full refund to the buyer. - **Refund** (`refunded-online`): Provide a `refund` object with a reason and reference. Optionally include `line_items` with `quantityRefunded` or `refund_amount` for a line-item refund, or `total_refund_amount` for an order-level partial refund. operationId: updateOrder tags: - Orders parameters: - $ref: '#/components/parameters/RetailerCode' - $ref: '#/components/parameters/MarketplaceCode' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderUpdateRequest' responses: '200': description: Order updated successfully content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Invalid state transition or bad request data content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/Error' components: securitySchemes: clientCredentials: type: apiKey in: header name: X-OMNIVORE-CLIENT-ID description: Client ID for API authentication (must be used together with X-OMNIVORE-CLIENT-SECRET) clientSecret: type: apiKey in: header name: X-OMNIVORE-CLIENT-SECRET description: Client secret for API authentication parameters: RetailerCode: name: retailer_code in: path description: Unique identifier code for the retailer required: true schema: type: string maxLength: 255 MarketplaceCode: name: marketplace_code in: path description: Unique identifier code for the marketplace (e.g., 'ebay', 'amazonau', 'trademe') required: true schema: type: string maxLength: 255 ListMax: name: max in: query description: Maximum number of orders to return per page required: false schema: type: integer minimum: 1 maximum: 100 default: 100 ListOffset: name: offset in: query description: Number of orders to skip for pagination required: false schema: type: integer minimum: 0 default: 0 ListOrderNumber: name: order_number in: query description: Filter by exact order number as created in the marketplace. Returns one or zero results. required: false schema: type: string maxLength: 255 example: "1234567890123-1234567890123" ListStatus: name: status in: query description: Filter orders by status required: false schema: type: string enum: - created - hold - quarantined - retailer-notified-failure - pending-payment-confirmed - pending-shipped - shipped - marked-shipped-failure - manual-fulfillment - pending-retailer-confirmation - retailer-cancellation - shopper-cancellation - refunded-online example: "pending-shipped" ListSort: name: sort in: query description: Field to sort results by required: false schema: type: string enum: - created - updated default: created ListOrder: name: order in: query description: Sort order direction required: false schema: type: string enum: - asc - desc default: desc ListCreatedAfter: name: created_after in: query description: Return orders created in Omnivore at or after this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" ListCreatedBefore: name: created_before in: query description: Return orders created in Omnivore at or before this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" ListUpdatedAfter: name: updated_after in: query description: Return orders updated in Omnivore at or after this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" ListUpdatedBefore: name: updated_before in: query description: Return orders updated in Omnivore at or before this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" ListCreatedInMarketplaceAfter: name: created_in_marketplace_after in: query description: Return orders created in the marketplace at or after this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" ListCreatedInMarketplaceBefore: name: created_in_marketplace_before in: query description: Return orders created in the marketplace at or before this date-time (ISO 8601) required: false schema: type: string format: date-time example: "2026-01-02T03:04:05Z" schemas: Order: type: object description: | An order received from a marketplace. Used as both the create request body and in all order responses (view, list, update). Server-generated fields (`id`, `created`, `updated`) are marked `readOnly` and are ignored when submitting a create request. required: - marketplace_code - order_number - status - total_price - customer - shipping_address - line_items properties: marketplace_code: type: string description: Code of the marketplace this order originated from maxLength: 255 example: "ebay" id: type: integer description: Omnivore internal order identifier, assigned on creation readOnly: true example: 262 order_number: type: string description: | Order number as assigned by the marketplace. Together with `marketplace_code` uniquely identifies the order. maxLength: 255 example: "1234567890123-1234567890123" alt_order_number: type: string description: Alternative order number (e.g., a secondary reference from the marketplace) maxLength: 255 nullable: true example: "12-34567-89012" retailer_order_id: type: integer description: Retailer's internal order ID, set via the update (acknowledge) call nullable: true example: 12345 retailer_order_number: type: string description: Retailer's internal order number, set via the update (acknowledge) call maxLength: 255 nullable: true example: "12345-ABC" status: type: string description: Current order status maxLength: 255 enum: - created - hold - quarantined - retailer-notified-failure - pending-payment-confirmed - pending-shipped - shipped - marked-shipped-failure - manual-fulfillment - pending-retailer-confirmation - retailer-cancellation - shopper-cancellation - refunded-online example: "created" total_price: $ref: '#/components/schemas/Price' additional_fee: $ref: '#/components/schemas/MoneyAmount' additional_tax: $ref: '#/components/schemas/MoneyAmount' customer: $ref: '#/components/schemas/Customer' billing_address: $ref: '#/components/schemas/Address' shipping_address: $ref: '#/components/schemas/Address' shipping: $ref: '#/components/schemas/Shipping' line_items: type: array description: Items in the order items: $ref: '#/components/schemas/LineItem' transactions: type: array description: Payment transactions associated with the order items: $ref: '#/components/schemas/Transaction' customer_message: type: string description: Message from the customer submitted at checkout maxLength: 255 nullable: true example: "If nobody is home, please leave at front door" created: type: string format: date-time description: Date and time the order was created in Omnivore readOnly: true example: "2026-03-02T15:26:44+11:00" updated: type: string format: date-time description: Date and time the order was last updated in Omnivore readOnly: true example: "2026-03-02T15:26:44+11:00" created_in_marketplace: type: string format: date-time description: Date and time the order was originally created in the marketplace example: "2019-12-01T12:00:00+11:00" OrderUpdateRequest: type: object description: | Request body for updating an order. `marketplace_code`, `order_number`, and `status` are always required. Additional fields depend on the update type — see the endpoint description for details of each scenario. required: - marketplace_code - order_number - status properties: marketplace_code: type: string description: Code of the marketplace this order belongs to maxLength: 255 example: "ebay" order_number: type: string description: Order number as assigned by the marketplace maxLength: 255 example: "1234567890123-1234567890123" status: type: string description: New order status to transition to maxLength: 255 enum: - created - hold - quarantined - retailer-notified-failure - pending-payment-confirmed - pending-shipped - shipped - marked-shipped-failure - manual-fulfillment - pending-retailer-confirmation - retailer-cancellation - shopper-cancellation - refunded-online example: "pending-shipped" retailer_order_id: type: integer description: Retailer's internal order ID (used when acknowledging an order) nullable: true example: 12345 retailer_order_number: type: string description: Retailer's internal order number (used when acknowledging an order) maxLength: 255 nullable: true example: "12345-ABC" shipping: $ref: '#/components/schemas/Shipping' line_items: type: array description: | Line items to partially ship or refund. Omit to ship or cancel the entire order. For refunds, omit and use `total_refund_amount` for an order-level partial refund. items: $ref: '#/components/schemas/UpdateLineItem' refund: $ref: '#/components/schemas/Refund' total_refund_amount: type: string description: Order-level partial refund amount (decimal string). Used instead of `line_items` for an order-wide refund. maxLength: 255 nullable: true example: "10.00" OrderListResponse: type: object description: Paginated list of orders properties: retailer: $ref: '#/components/schemas/Retailer' total_count: type: integer description: Total number of orders matching the filter criteria minimum: 0 example: 2 current_count: type: integer description: Number of orders in the current response minimum: 0 example: 2 sort: type: string description: Field used for sorting example: "created" order: type: string description: Sort order direction enum: - asc - desc example: "desc" offset: type: integer description: Number of orders skipped (pagination offset) minimum: 0 example: 0 max: type: integer description: Maximum orders per page minimum: 1 example: 100 orders: type: array description: List of orders items: $ref: '#/components/schemas/Order' Price: type: object description: | Price with tax breakdown. `without_tax` is present in order totals and shipping prices but may be absent in line-item unit prices. required: - with_tax - tax - currency properties: with_tax: type: string description: Price including tax (decimal string) maxLength: 255 example: "27.50" without_tax: type: string description: Price excluding tax (decimal string) maxLength: 255 example: "25.00" tax: type: string description: Tax amount (decimal string) maxLength: 255 example: "2.50" currency: type: string description: ISO 4217 currency code minLength: 3 maxLength: 3 example: "AUD" MoneyAmount: type: object description: A monetary amount with currency, used for fees and taxes required: - amount - currency properties: amount: type: string description: Amount as a decimal string maxLength: 255 example: "0.00" currency: type: string description: ISO 4217 currency code minLength: 3 maxLength: 3 example: "AUD" Customer: type: object description: Customer contact details required: - first_name - last_name - email properties: first_name: type: string description: Customer's first name maxLength: 255 example: "John" last_name: type: string description: Customer's last name maxLength: 255 example: "Smith" email: type: string description: Customer's email address format: email maxLength: 255 example: "john@example.com" Address: type: object description: Physical address, used for both billing and shipping required: - first_name - last_name - line1 - city - postcode - country_code properties: first_name: type: string description: First name of the address recipient maxLength: 255 example: "John" last_name: type: string description: Last name of the address recipient maxLength: 255 example: "Smith" line1: type: string description: First line of the street address maxLength: 255 example: "123 Beach St" line2: type: string description: Second line of the street address (unit, apartment, etc.) maxLength: 255 nullable: true example: "" city: type: string description: City or suburb maxLength: 255 example: "Sydney" state: type: string description: State or territory code maxLength: 255 example: "NSW" postcode: type: string description: Postal or ZIP code maxLength: 255 example: "2000" phone: type: string description: Contact phone number maxLength: 255 nullable: true example: "0412345678" country_name: type: string description: Full country name maxLength: 255 example: "Australia" country_code: type: string description: ISO 3166-1 alpha-2 country code minLength: 2 maxLength: 2 example: "AU" Shipping: type: object description: | Shipping information. In responses all four fields are present (carrier and tracking_code may be null before shipment). In update requests, provide only `carrier` and `tracking_code`. properties: price: $ref: '#/components/schemas/Price' carrier: type: string description: Name of the shipping carrier maxLength: 255 nullable: true example: "Australia Post" method: type: string description: Shipping method code as specified by the marketplace maxLength: 255 nullable: true example: "AU_StandardDelivery" tracking_code: type: string description: Shipment tracking code provided by the carrier maxLength: 255 nullable: true example: "ABC1234567890" LineItem: type: object description: An individual item within an order required: - product_sku - variant_sku - marketplace_sku - name - unit_price - quantity properties: id: type: integer description: Omnivore internal line item identifier readOnly: true example: 288 product_sku: type: string description: SKU of the parent product in the retailer's catalogue maxLength: 255 example: "TEST1" variant_sku: type: string description: SKU of the specific product variant maxLength: 255 example: "TEST1" marketplace_sku: type: string description: SKU as used by the marketplace for this item maxLength: 255 example: "TEST1" name: type: string description: Display name of the product maxLength: 255 example: "Test 1 Example Product" unit_price: $ref: '#/components/schemas/Price' quantity: type: integer description: Number of units ordered minimum: 1 example: 2 delivery_amount: type: string description: Per-item delivery cost (decimal string) maxLength: 255 nullable: true example: "0.00" UpdateLineItem: type: object description: | Line item reference used in order update requests for partial shipments and partial refunds. Provide `quantityShipped` when shipping; provide `quantityRefunded` or `refund_amount` when refunding. required: - product_sku - variant_sku properties: product_sku: type: string description: SKU of the parent product maxLength: 255 example: "TEST1" variant_sku: type: string description: SKU of the specific variant maxLength: 255 example: "TEST1" quantityShipped: type: integer description: Number of units being shipped in this partial shipment minimum: 1 nullable: true example: 2 quantityRefunded: type: integer description: Number of units to refund (alternative to `refund_amount`) minimum: 1 nullable: true example: 1 refund_amount: type: string description: Amount to refund for this line item (decimal string, alternative to `quantityRefunded`) maxLength: 255 nullable: true example: "7.00" Transaction: type: object description: A payment transaction associated with an order properties: amount: type: string description: Transaction amount (decimal string) maxLength: 255 example: "27.50" currency: type: string description: ISO 4217 currency code minLength: 3 maxLength: 3 example: "AUD" transaction_id: type: string description: Unique transaction identifier from the payment provider maxLength: 255 example: "1234567890" code: type: string description: Transaction code as provided in the create request maxLength: 255 nullable: true example: "1234567890" type: type: string description: Payment method or provider type (e.g., 'marketplace', 'paypal') maxLength: 255 example: "marketplace" response_code: type: string description: Response code returned by the payment provider maxLength: 255 example: "200" status: type: string description: Current status of the transaction maxLength: 255 example: "Complete" Refund: type: object description: Refund details supplied when setting an order to `refunded-online` required: - reason properties: reason: type: string description: Reason for the refund maxLength: 255 example: "Damaged goods" reference: type: string description: External reference number for the refund (e.g., issued by the marketplace) maxLength: 255 nullable: true example: "33WDL500722366600655001" Retailer: type: object description: Retailer information returned in list responses properties: code: type: string description: Unique retailer code maxLength: 255 example: "test-store" name: type: string description: Retailer display name maxLength: 255 example: "Test Store" currency: type: string description: Default currency for the retailer (ISO 4217) minLength: 3 maxLength: 3 example: "AUD" Error: type: object description: Error response properties: error: type: string description: Human-readable error message maxLength: 255 example: "Retailer test-store order 1234567890123-1234567890123 is forbidden to change from state created to pending-shipped, aborting"