Table of contents:

About

Simply put an Order is a collection of line items. A line item is a product times quantity. Order processing revolves around figuring available shipping options for the set of line items, pricing and taxes, availability and once the shipping has been chosen and payment made inserting the order into the merchant’s store.

Price discrepancies

It might occur that the product on 1o’s side was priced differently than the same product in the merchant’s store. This is usually due to legal agreements between 1o and the merchant. To account for possible differences the integration should ensure line items prices of the inserted order match those coming from 1o GraphQL API order.lineItems.price.

This can usually be achieved by changing line items on the inserted order. Options vary between the price or applying discounts on individual line items.

Servicing the update_available_shipping_rates directive

When an order on 1o is created or updated, 1o might issue this directive to your integration.

{
  "directives": [
    {
      "args": {
        "order_id": "91997424-0c62-4525-8043-f00de23cb91c"
      },
      "directive": "update_available_shipping_rates",
      "id": "45a42385-8ebd-45bb-9ac8-c7365aa157ac"
    }
  ]
}

Once your integration has calculated shipping rates for the given order, it should use a mutation to update the order with this new information:

mutation UpdateShippingRatesExample($id: ID!, $input: OrderInput!) {
  updateOrder(id: $id, input: $input) {
    id
    shippingRates {
      handle
      amount
      title
    }
  }
}

{
  "id": "235c9162-80c2-4fd4-9eb8-e398ed130329",
	"input": {
		"shippingRates": [
			{
			  "handle": "economy-international-4.50",
			  "title": "Economy International",
			  "amount": 450
			},
			{
			  "handle": "express-international-15.0",
			  "title": "Express International",
				"amount": 1500
			}
		]
	}
}

Each shipping rate is specified with the following fields:

• handle is internal to you, the integrator. In the above example, the format is borrowed from Shopify and includes the amount (which makes it work like a cache key, smart!)
• title is the title that 1o will display to the buyer during the checkout process (among other places)
• amount is the decimal amount represented in cents (as an integer). You should assume that the currency here is the same as the one used on the order (but let’s talk about this soon to see if the assumption is sane).

When shipping rates for an order can’t be calculated, 1o expects the integration to set the shippingRatesError field instead. For example, let’s consider the case where an order can’t be shipped to a given country:

{
  "id": "235c9162-80c2-4fd4-9eb8-e398ed130329",
	"input": {
    "shippingRatesError": {
	    "code": "no_shipping_rates",
	    "userMessage": "Unfortunately, we're unable to ship to your address.",
	    "details": "(This is optional.)"
    }
	}
}

"no_shipping_rates" is the only recognized error code at the moment of writing. However, your integration is free to set custom error codes for other purposes.