Sign in

v1

latestOpenAPI 3.1.02026-07-2689175245.8 KB
Orders

Upsert Order

Upsert an order using the external_id.

put/orders

Request body

external_idstring required

External ID of the order.

namestring required

The name of the order.

secondary_identifierstring nullable

An optional secondary identifier for the order, enabling customer lookup by an alternate reference. Use this for any supplementary order ID your system tracks — for example a fulfillment system ID (e.g. NetSuite), a marketplace order number, or a confirmation number. Customers can look up their return using either name or secondary_identifier.

sales_channelstring required

If a channel with this name is not already associated with the shop, it will be used to create a new channel.

status'active' | 'archived' | 'cancelled' | 'unknown' required

Status of the Order.

taxes_includedboolean required
tagsTagRequestData[] nullable
created_atstring date-time
updated_atstring date-time
cancelled_atstring date-time
financial_status'pending' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'voided' | 'null' nullable

The financial status of the order.

cancel_reason'customer' | 'declined' | 'fraud' | 'inventory' | 'other' | 'staff' | 'null' nullable

The reason the order was cancelled, if applicable.

processed_atstring date-time
client_details_user_agentstring nullable

The user agent string of the browser used to place the order.

Example request

{
  "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
  "sales_channel": "shopify",
  "customer": {
    "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c"
  },
  "shipping_address": {
    "id": 23432434,
    "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
    "created_at": "2021-10-01T03:30:15.000Z",
    "updated_at": "2021-10-01T03:30:15.000Z",
    "name": "Staples",
    "company": "Example Company",
    "address1": "1747 Olentangy River Rd",
    "city": "Columbus",
    "state": "OH",
    "zip": "43212",
    "country": "United States of America",
    "country_code": "US",
    "latitude": 39.995329,
    "longitude": -83.026838
  },
  "billing_address": {
    "id": 23432434,
    "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
    "created_at": "2021-10-01T03:30:15.000Z",
    "updated_at": "2021-10-01T03:30:15.000Z",
    "name": "Staples",
    "company": "Example Company",
    "address1": "1747 Olentangy River Rd",
    "city": "Columbus",
    "state": "OH",
    "zip": "43212",
    "country": "United States of America",
    "country_code": "US",
    "latitude": 39.995329,
    "longitude": -83.026838
  },
  "total_price": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_price_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_discounts": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_discounts_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_taxes": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_taxes_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "order_discounts": [
    [
      {
        "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
        "tax_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        },
        "net_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        }
      }
    ]
  ],
  "shipping_lines": [
    {
      "price": {
        "amount": 50000,
        "currency_code": "USD"
      },
      "discounts": {
        "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
        "net_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        },
        "tax_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        }
      },
      "tax_lines": [
        {
          "price": {
            "amount": 50000,
            "currency_code": "USD"
          }
        }
      ]
    }
  ],
  "refunds": [
    [
      {
        "amount": {
          "amount": 50000,
          "currency_code": "USD"
        },
        "created_at": "2023-04-25T13:25:00-05:00",
        "updated_at": "2023-04-25T13:25:00-05:00"
      }
    ]
  ],
  "line_items": [
    [
      {
        "line_item_id": "293482039",
        "provider_line_item_id": "23984238720",
        "product_id": "29871298310292",
        "variant_id": "23498287203948",
        "sku": "2039473-Y",
        "title": "Black Striped Shirt",
        "price": "78.00",
        "discount": "0.00",
        "tax": "4.29",
        "refund": "31.65",
        "refund_item": "27.36",
        "refund_tax": "4.29",
        "refund_shipping": "4.00",
        "refund_excluding_shipping": "27.65",
        "refund_shipping_tax": "0.40",
        "refund_excluding_shipping_tax": "4.29",
        "returned_at": "2023-01-01T22:27:16.000Z",
        "return_reason": "I like another style more",
        "parent_return_reason": "Didn't like it",
        "return_comment": "N/A",
        "barcode": "290832428347",
        "outcome": "default",
        "consolidation_tracking": "MS6681181",
        "consolidation_destination_id": "357",
        "condition": {
          "description": "Grade A: No refurbishment needed",
          "condition_category": "grade_c",
          "return_processor": "warehouse-operator@example.com",
          "note": "This item is missing the original packaging. Light refurbishment required. Scuff marks on the back of the item.",
          "inspected_at": "2023-07-19T15:11:32+00:00",
          "images": [
            "https://example.com/image.jpg"
          ]
        },
        "disposition": {
          "return_processor": "warehouse-operator@example.com",
          "note": "This item will be returned to stock after bagging and tagging",
          "inspected_at": "2023-07-19T15:11:32+00:00"
        }
      }
    ]
  ],
  "fulfillments": [
    {
      "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
      "fulfilled_at": "2023-04-25T13:25:00-05:00",
      "fulfillment_line_items": [
        {
          "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
          "order_line_item_external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c"
        }
      ]
    }
  ],
  "tags": [
    "VIP"
  ],
  "created_at": "2023-04-25T13:25:00-05:00",
  "updated_at": "2023-04-25T13:25:00-05:00",
  "cancelled_at": "2023-04-25T13:25:00-05:00",
  "processed_at": "2023-04-25T13:25:00-05:00",
  "total_tip_received": {
    "amount": 50000,
    "currency_code": "USD"
  }
}

Response

OK

Example response

{
  "order": {
    "id": 810772123123123,
    "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
    "sales_channel": "shopify",
    "customer": {
      "id": 123123123123123,
      "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
      "sales_channel": "shopify"
    },
    "shipping_address": {
      "id": 23432434,
      "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
      "created_at": "2021-10-01T03:30:15.000Z",
      "updated_at": "2021-10-01T03:30:15.000Z",
      "name": "Staples",
      "company": "Example Company",
      "address1": "1747 Olentangy River Rd",
      "city": "Columbus",
      "state": "OH",
      "zip": "43212",
      "country": "United States of America",
      "country_code": "US",
      "latitude": 39.995329,
      "longitude": -83.026838
    },
    "billing_address": {
      "id": 23432434,
      "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
      "created_at": "2021-10-01T03:30:15.000Z",
      "updated_at": "2021-10-01T03:30:15.000Z",
      "name": "Staples",
      "company": "Example Company",
      "address1": "1747 Olentangy River Rd",
      "city": "Columbus",
      "state": "OH",
      "zip": "43212",
      "country": "United States of America",
      "country_code": "US",
      "latitude": 39.995329,
      "longitude": -83.026838
    },
    "total_price": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "total_price_presentment": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "total_discounts": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "total_discounts_presentment": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "shipping_lines": [
      {
        "price": {
          "amount": 50000,
          "currency_code": "USD"
        },
        "discounts": {
          "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
          "net_adjustment_money": {
            "amount": 50000,
            "currency_code": "USD"
          },
          "tax_adjustment_money": {
            "amount": 50000,
            "currency_code": "USD"
          }
        },
        "tax_lines": [
          {
            "price": {
              "amount": 50000,
              "currency_code": "USD"
            }
          }
        ]
      }
    ],
    "order_discounts": [
      {
        "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
        "tax_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        },
        "net_adjustment_money": {
          "amount": 50000,
          "currency_code": "USD"
        }
      }
    ],
    "total_taxes": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "total_taxes_presentment": {
      "amount": 50000,
      "currency_code": "USD"
    },
    "tags": [
      "VIP"
    ],
    "refunds": [
      [
        [
          {
            "amount": {
              "amount": 50000,
              "currency_code": "USD"
            },
            "created_at": "2023-04-25T13:25:00-05:00",
            "updated_at": "2023-04-25T13:25:00-05:00"
          }
        ]
      ]
    ],
    "line_items": [
      [
        {
          "line_item_id": "293482039",
          "provider_line_item_id": "23984238720",
          "product_id": "29871298310292",
          "variant_id": "23498287203948",
          "sku": "2039473-Y",
          "title": "Black Striped Shirt",
          "price": "78.00",
          "discount": "0.00",
          "tax": "4.29",
          "refund": "31.65",
          "refund_item": "27.36",
          "refund_tax": "4.29",
          "refund_shipping": "4.00",
          "refund_excluding_shipping": "27.65",
          "refund_shipping_tax": "0.40",
          "refund_excluding_shipping_tax": "4.29",
          "returned_at": "2023-01-01T22:27:16.000Z",
          "return_reason": "I like another style more",
          "parent_return_reason": "Didn't like it",
          "return_comment": "N/A",
          "barcode": "290832428347",
          "outcome": "default",
          "consolidation_tracking": "MS6681181",
          "consolidation_destination_id": "357",
          "condition": {
            "description": "Grade A: No refurbishment needed",
            "condition_category": "grade_c",
            "return_processor": "warehouse-operator@example.com",
            "note": "This item is missing the original packaging. Light refurbishment required. Scuff marks on the back of the item.",
            "inspected_at": "2023-07-19T15:11:32+00:00",
            "images": [
              "https://example.com/image.jpg"
            ]
          },
          "disposition": {
            "return_processor": "warehouse-operator@example.com",
            "note": "This item will be returned to stock after bagging and tagging",
            "inspected_at": "2023-07-19T15:11:32+00:00"
          }
        }
      ]
    ],
    "fulfillments": [
      {
        "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
        "fulfilled_at": "2023-04-25T13:25:00-05:00",
        "fulfillment_line_items": [
          {
            "external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c",
            "order_line_item_external_id": "564400c7-7a6b-4f29-b6a5-7bb580b2992c"
          }
        ]
      }
    ],
    "created_at": "2023-04-25T13:25:00-05:00",
    "updated_at": "2023-04-25T13:25:00-05:00",
    "processed_at": "2023-04-25T13:25:00-05:00",
    "total_tip_received": {
      "amount": 50000,
      "currency_code": "USD"
    }
  }
}