Commerce API Reference

Welcome to the Commerce API! You can use this API to retrieve products, SKUs, payment methods, etc, as well as create baskets, basket items, orders and payments.

These docs contain code examples in cUrl - you can view these in the dark area to the right.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer api_key"

Make sure to replace api_key with your API key.

Goods uses API keys to allow access to the Commerce API. You can register a new API key for a shop by logging in to Goods Platform, going to the shop, then Settings and then Users.

Goods expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer api_key

Example - create an order

Step 1: create a basket

curl "https://api.goods.co.uk/commerce/baskets"
    -X "POST"
    -H 'Authorization: Bearer api_key'

    -d $'{"data": {}}'

Step 2: create a basket item for SKU ID 1 and quantity 1

curl "https://api.goods.co.uk/commerce/basket-items"
    -X "POST"
    -H 'Authorization: Bearer api_key'
    -d $'{
  "data": {
    "attributes": {
      "quantity": 1
    },
    "relationships": {
      "basket": {
        "data": {
          "id": "26c266ee-9936-431a-8d3f-f4b3bc8f978f",
          "type": "baskets"
        }
      },
      "sku": {
        "data": {
          "id": "1",
          "type": "skus"
        }
      }
    }
  }
}'

Step 3: create an order from the basket with the customer's details

curl "https://api.goods.co.uk/commerce/orders"
    -X "POST"
    -H 'Authorization: Bearer api_key'
    -d $'{
  "data": {
    "attributes": {
      "phone-number": "0123456789",
      "mobile-number": "",
      "billing-address1": "1 Infinite Loop",
      "billing-address2": "",
      "billing-city": "London",
      "billing-country": "GB",
      "email-address": "[email protected]",
      "billing-region": "",
      "name": "John Smith",
      "billing-postcode": "W1 1AA"
    },
    "type": "orders",
    "relationships": {
      "basket": {
        "data": {
          "type": "baskets",
          "id": "26c266ee-9936-431a-8d3f-f4b3bc8f978f"
        }
      }
    }
  }
}

Step 4: create a payment for the order using shop payment method 1

curl "https://api.goods.co.uk/commerce/payments"
    -X "POST"
    -H 'Authorization: Bearer api_key'

    -d $'{
  "data": {
    "attributes": {
      "amount": "10000",
      "capture": "true"
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "1234567891234"
        }
      },
      "shop-payment-method": {
        "data": {
          "type": "shop-payment-methods",
          "id": "1"
        }
      }
    }
  }
}'

This is an example of how, from start to finish, a fully paid order can be created.

Step 1: Create a basket

First up a basket must be created. Baskets can have items added and removed, be modified, etc.

Step 2: Create a basket item

Next, basket items must be created (otherwise nothing is being bought!). Basket items will need SKU and quantity.

Step 3: Create an order from the basket

Once the basket is ready (all basket items created), an order can be created from the basket.

Step 4: Create a payment for the order

Finally payments can be added to order. In most cases the shop will be setup to automatically fulfil the order once the order balance reaches zero.

Baskets

Create a Basket

curl "https://api.goods.co.uk/commerce/baskets"
  -X "POST"
  -H 'Authorization: Bearer api_key'
  -d $'{"data": {}}'

The above command returns JSON structured like this:

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "id": "12345678-1234-1234-1234-123456789012",
    "type": "basket",
    "relationships": {
      "shop": { "data": { "type": "shop", "id": "1" } },
      "basket-items": { "data": [] }
    },
    "attributes": { "total": 0, "quantity": 0 }
  }
}

This endpoint is used to create a basket

HTTP Request

POST https://api.goods.co.uk/commerce/baskets

Payload

The payload should be in json-api format.

Basket items

Create a Basket Item

curl "https://api.goods.co.uk/commerce/basket-items"
    -X "POST"
    -H 'Authorization: Bearer api_key'
    -d $'{
  "data": {
    "attributes": {
      "quantity": 1
    },
    "relationships": {
      "basket": {
        "data": {
          "id": "12345678-1234-1234-1234-123456789012",
          "type": "baskets"
        }
      },
      "sku": {
        "data": {
          "id": "1",
          "type": "skus"
        }
      }
    }
  }
}'

The above command returns JSON structured like this:

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "id": "99999999-9999-9999-9999-999999999999",
    "type": "basket-item",
    "relationships": {
      "sku": { "data": { "type": "sku", "id": "1" } },
      "basket": {
        "data": {
          "type": "basket",
          "id": "12345678-1234-1234-1234-123456789012"
        }
      }
    },
    "attributes": {
      "quantity": 1,
      "price": 10000,
      "metadata": null,
      "is-hidden": false,
      "inserted-at": "2017-01-01T00:00:00.000000Z"
    }
  }
}

This endpoint is used to create a basket item

HTTP Request

POST https://api.goods.co.uk/commerce/basket-items

Payload

The payload should be in json-api format.

Attributes

Parameter	Required	Description
quantity	yes	The quantity of the SKU this basket item contains

Relationships

Type	Required	Description
sku	yes	The SKU that the basket item represents

Orders

Create an Order

curl "https://api.goods.co.uk/commerce/orders"
    -X "POST"
    -H 'Authorization: Bearer api_key'
    -d $'{
  "data": {
    "attributes": {
      "phone-number": "0123456789",
      "mobile-number": "",
      "billing-address1": "1 Infinite Loop",
      "billing-address2": "",
      "billing-city": "London",
      "billing-country": "GB",
      "email-address": "[email protected]",
      "billing-region": "",
      "name": "John Smith",
      "billing-postcode": "W1 1AA"
    },
    "type": "orders",
    "relationships": {
      "basket": {
        "data": {
          "type": "baskets",
          "id": "12345678-1234-1234-1234-123456789012"
        }
      }
    }
  }
}

The above command returns JSON structured like this:

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "id": "1234567890123",
    "type": "order",
    "attributes": {
      "total": 10000,
      "status": "reserved",
      "shipping-region": null,
      "shipping-postcode": null,
      "shipping-country": null,
      "shipping-city": null,
      "shipping-address2": null,
      "shipping-address1": null,
      "quantity": 1,
      "phone-number": "01234567890",
      "name": "John Smith",
      "mobile-number": null,
      "inserted-at": "2017-01-01T00:00:00.000000Z",
      "email-address": "[email protected]",
      "billing-region": null,
      "billing-postcode": "W1 1AA",
      "billing-country": "GB",
      "billing-city": "London",
      "billing-address2": null,
      "billing-address1": "1 Infinite Loop",
      "balance": 10000,
      "amount-paid": 0
    },
    "relationships": {
      "shop": { "data": { "type": "shop", "id": "1" } },
      "payments": { "data": [] },
      "order-payment-methods": {
        "data": [{ "type": "order-payment-method", "id": "1" }]
      },
      "order-lines": {
        "data": [{ "type": "order-line", "id": "9876543210987" }]
      },
      "customer": { "data": { "type": "customer", "id": "1" } },
      "basket": {
        "data": {
          "type": "basket",
          "id": "12345678-1234-1234-1234-123456789012"
        }
      }
    }
  }
}

This endpoint is used to create an order

HTTP Request

POST https://api.goods.co.uk/commerce/orders

Payload

The payload should be in json-api format.

Attributes

Parameter	Required	Description
name	yes	Customers full name
email-address	yes	Customer's email address
phone-number	yes	Customer's primary phone number
mobile-number	optional	Customer's mobile phone number
billing-address1	yes	Billing address first line
billing-address2	optional	Billing address second line
billing-city	yes	Billing address city
billing-region	optional	Billing address region (e.g. county or state)
billing-postcode	yes	The postcode or zipcode
billing-country	yes	The two letter country code (e.g. GB)
shipping-address1	optional	Shipping address first line
shipping-address2	optional	Shipping address second line
shipping-city	optional	Shipping address city
shipping-region	optional	Shipping address region (e.g. county or state)
shipping-postcode	optional	The postcode or zipcode
shipping-country	optional	The two letter country code (e.g. GB)

Relationships

Type	Required	Description
basket	yes	The basket that the order should be created from

Includes

As per the JSON API spec related resources can be included in the response payload. These can be requested by adding a parameter to request with the key include and the value as a comma separated list of the desired resources.

e.g. include: "order_payment_methods,order_lines"

Type	Description
order_lines	The order lines related to this order.
order_payment_methods	The order payment methods available for this order. These will contain the shop_payment_method and the max_payable_amount that can be processed by that payment method

Payments

Create a Payment

curl "https://api.goods.co.uk/commerce/payments"
    -X "POST"
    -H 'Authorization: Bearer api_key'

    -d $'{
  "data": {
    "attributes": {
      "amount": "10000",
      "capture": "true"
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "1234567891234"
        }
      },
      "shop-payment-method": {
        "data": {
          "type": "shop-payment-methods",
          "id": "1"
        }
      }
    }
  }
}'

The above command returns JSON structured like this:

{
  "jsonapi": { "version": "1.0" },
  "id": "abcdef12-abcd-abcd-abcd-abcdef123456",
  "data": {
    "type": "payment",
    "relationships": {
      "shop-payment-method": {
        "data": { "type": "shop-payment-method", "id": "1" }
      },
      "order": { "data": { "type": "order", "id": "1234567891234" } }
    },
    "attributes": { "token": null, "amount": 10000 }
  }
}

This endpoint is used to create a payment

HTTP Request

POST https://api.goods.co.uk/commerce/payments

Payload

The payload should be in json-api format.

Attributes

Parameter	Required	Description
amount	yes	The amount to be paid
capture	yes	Take payment immediately or just authorize
card-number	optional	Full card number
cardholder	optional	Card holders full name
valid-from	optional	Card valid from date (e.g. 0117)
expiry-date	optional	Card expiry date (e.g. 0120)
issue-number	optional	Card issue number
cvv	optional	CVV card security code
token	optional	Token payment string

Relationships

Type	Required	Description
order	yes	The order linked to the payment
shop-payment-method	yes	The shop payment method to use for the payment

Includes

As per the JSON API spec related resources can be included in the response payload. These can be requested by adding a parameter to request with the key include and the value as a comma separated list of the desired resources.

e.g. include: "order,order.order_lines"

Type	Description
order	The order linked to the payment.
order.order_lines	The order lines linked to the payment.
order.order_payment_methods	The updated order payment methods available for this order. Each order payment method will have had its amount_payable adjusted now that at least one payment has been created.

Products

Get Products

curl "https://api.goods.co.uk/commerce/products"
  -H "Authorization: api_key"
  -d $'{}'

The above command returns JSON structured as JSON-API like this:

{
  "jsonapi": { "version": "1.0" },
  "data": [
    {
      "id": "1",
      "type": "product",
      "attributes": {
        "name": "T-shirt",
        "slug": "t-shirt",
        "description": "This is a really great T-shirt",
        "summary": "Great T-shirt"
      },
      "relationships": {
        "skus": {
          "data": [{ "type": "sku", "id": "1" }]
        },
        "product-fields": { "data": [] },
        "organisation": { "data": { "type": "organisation", "id": "1" } },
        "brand": { "data": { "type": "brand", "id": "1" } }
      }
    }
  ],
  "meta": { "total": 1 }
}

This endpoint retrieves all products.

HTTP Request

GET https://api.goods.co.uk/commerce/products

Query Parameters

Parameter	Type	Description
filter[slug]	String	Filter the list of products by slug.
filter[query]	String	Return any products where a substring of name matches the query

Get a Specific Product

curl "https://api.goods.co.uk/commerce/products/1"
  -H "Authorization: api_key"
  -d $'{}'

The above command returns JSON structured as JSON-API like this:

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "id": "1",
    "type": "product",
    "attributes": {
      "name": "T-shirt",
      "slug": "t-shirt",
      "description": "This is a really great T-shirt",
      "summary": "Great T-shirt"
    },
    "relationships": {
      "skus": {
        "data": [{ "type": "sku", "id": "1" }]
      },
      "product-fields": { "data": [] },
      "organisation": { "data": { "type": "organisation", "id": "1" } },
      "brand": { "data": { "type": "brand", "id": "1" } }
    }
  }
}

This endpoint retrieves a specific product.

HTTP Request

GET https://api.goods.co.uk/commerce/products/<ID>

URL Parameters

Parameter	Description
ID	The ID of the product to retrieve

SKUs

Get SKUs

curl "https://api.goods.co.uk/commerce/skus"
  -H "Authorization: api_key"
  -d $'{}'

The above command returns JSON structured as JSON-API like this:

{
  "jsonapi": { "version": "1.0" },
  "data": [
    {
      "id": "1",
      "type": "sku",
      "relationships": {
        "sku-images": { "data": [] },
        "sku-fields": {
          "data": [{ "type": "sku-field", "id": "1" }]
        },
        "product": { "data": { "type": "product", "id": "1" } }
      },
      "attributes": { "stock-quantity": 9999, "price": 1999 }
    }
  ],
  "included": [
    {
      "type": "sku-field",

      "id": "1",
      "attributes": {
        "values": ["Blue T-shirt"],
        "slug": "name",
        "name": "Name"
      },
      "relationships": { "sku": { "data": { "type": "sku", "id": "1" } } }
    }
  ]
}

This endpoint retrieves all skus.

HTTP Request

GET https://api.goods.co.uk/commerce/skus

Query Parameters

Parameter	Type	Description
filter[product_id]	Integer	Filter by a specific product id
filter[product_slug]	Integer	Filter by a specific product slug

Advanced SKU Field Filtering

SKUs can be filtered using their custom fields by constructing a more complex query.

This takes the form of an array of queries of the form [slug][operator][value] that is placed in the filter[query] parameter.

For example:

Parameter	Value
filter[query][0][]	"name"
filter[query][0][]	"like"
filter[query][0][]	"Blue T-shirt"
filter[query][1][]	"price"
filter[query][1][]	"<="
filter[query][1][]	"1000"
filter[query][2][]	"is_favourite"
filter[query][2][]	"="
filter[query][2][]	"true"

Operators

The list of operators that be used in SKU field filtering.

Operator	Field types	Description
like	String	Case insensitive string comparison
=	Integer, Float, Boolean	Equality
<	Integer, Float	Less than value
<=	Integer, Float	Less than or equal to value
>	Integer, Float	Greater than value
>=	Integer, Float	Greater than or euqal to value
is_same	Date	Date is equal to value
is_before	Date	Date is before value
is_same_or_before	Date	Date is equal to or before value
is_after	Date	Date is after value
is_same_or_after	Date	Date is equal to or after value

Get a Specific SKU

curl "https://api.goods.co.uk/commerce/skus/1"
  -H "Authorization: api_key"
  -d $'{}'

The above command returns JSON structured like this:

{
  "jsonapi": { "version": "1.0" },
  "id": "1",
  "attributes": { "stock-quantity": 9999, "price": 1999 },
  "data": {
    "type": "sku",
    "relationships": {
      "sku-images": { "data": [] },
      "sku-fields": {
        "data": [{ "type": "sku-field", "id": "1" }]
      },
      "product": { "data": { "type": "product", "id": "1" } }
    }
  },
  "included": [
    {
      "type": "sku-field",
      "relationships": { "sku": { "data": { "type": "sku", "id": "1" } } },
      "id": "1",
      "attributes": {
        "values": ["Blue T-shirt"],
        "slug": "name",
        "name": "Name"
      }
    }
  ]
}

This endpoint retrieves a specific SKU.

HTTP Request

GET https://api.goods.co.uk/commerce/skus/<ID>

URL Parameters

Parameter	Description
ID	The ID of the SKU to retrieve