Checkouts

You have to pass through the checkout process to place an order with your product variants.


Create

Attribute

Field Type Description Required
external_reference string External reference may be use to specifies where an order originally came from.
external_identifier string External identifier may be used to reference an order from another external system. We do not check for uniqueness!
cost_centre string Cost centre will be printed on packing slip.
email string E-mail. RFC3696/5321 compliant yes
items array Items. An array of Item Objects yes
shipping_address object Shipping address. Address Object yes
billing_address object Billing address. If you do not specify this address, it corresponds to the shipping address. Address Object
whitelabel_address object White label / Sender address. Address Object

Item Object

Back to Attributes

Field Type Description Required
variant_id integer Id of the product variant yes
quantity integer The quantity to be ordered yes

Address Object

Back to Attributes

Field Type Description Required
company string Company
first_name string First name yes
last_name string Last name yes
street1 string First street line. Limited to 35 characters yes
street2 string Second street line. Limited to 35 characters
street3 string Third street line. Limited to 35 characters
zip string Zip code yes
city string City yes
province_code string Requires a two-digit code. Example: 'AL' (Alabama) Only for shipments to the United States and Canada.
country_code ISO 3166-1-alpha-2 code (ISO 2 country code) Example: 'US' or 'DE'. All accepted values can be found on the Official ISO website. yes
email string Contact person's e-mail address, RFC3696/5321 compliant. yes
phone string So that, for example, the parcel service can call the address/dispatcher of the parcel in case of problems with shipping. yes
vat_in string Sales tax

Example

{primary.fa-paper-plane} Request

POST /checkouts HTTP/1.1

{
   "email": "customer@example.com",
   "cost_centre": "lorem 1234",
   "items": [
      {
         "variant_id": 1,
         "quantity": 1
      }
   ],
   "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street1": "123 Main St",
      "zip": "12345",
      "city": "Anytown",
      "country_code": "DE",
      "province_code": "NW",
      "phone": "12345 67890",
      "email": "shipping@example.com"
   }
}

{success} Response

HTTP/1.1 201 Created

{
    "id": 1,
    "is_test": true,
    "external_identifier": null,
    "external_reference": null,
    "cost_centre": "lorem 1234",
    "state": "incompleted",
    "customer_locale": "en",
    "currency": "EUR",
    "total": 123.75,
    "subtotal": 103.99,
    "total_tax": 19.76,
    "total_items_price": 123.75,
    "shipping_line": [],
    "created_at": "2017-09-29T09:14:11+00:00",
    "updated_at": "2017-09-29T09:14:11+00:00",
    "cancelled_at": null,
    "items": [
        {
            "id": 75,
            "quantity": 1,
            "total": 123.75,
            "price": 103.99,
            "total_tax": 19.76,
            "tax_rate": 19,
            "variant": {
                "id": 1,
                "total": 123.75,
                "price": 103.99,
                "tax": 19.76,
                "tax_rate": 19,
                "attributes": [
                    {
                        "name": "color",
                        "value": "LightPink"
                    },
                    {
                        "name": "size",
                        "value": "M"
                    }
                ],
                "origin": {
                    "code": "2032095419441"
                },
                "media_id": 81,
                "views": [],
                "state": "finished",
                "created_at": "2017-09-27T10:10:33+00:00",
                "updated_at": "2017-09-27T10:10:34+00:00"
            },
            "created_at": "2017-09-29T09:14:11+00:00",
            "updated_at": "2017-09-29T09:14:11+00:00",
            "cancelled_at": null
        }
    ],
    "customer": {
        "id": 98,
        "first_name": null,
        "last_name": null,
        "email": "customer@example.com",
        "phone": null,
        "addresses": [],
        "default_address": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "shipping_address": {
        "id": 190,
        "default": true,
        "company": null,
        "first_name": "John",
        "last_name": "Doe",
        "city": "Anytown",
        "street1": "123 Main St",
        "street2": null,
        "street3": null,
        "zip": "12345",
        "phone": "12345 67890",
        "email": "shipping@example.com",
        "province_code": "NW",
        "country_code": "DE",
        "vat_in": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "billing_address": {
        "id": 191,
        "default": true,
        "company": null,
        "first_name": "John",
        "last_name": "Doe",
        "city": "Anytown",
        "street1": "123 Main St",
        "street2": null,
        "street3": null,
        "zip": "12345",
        "phone": "12345 67890",
        "email": "shipping@example.com",
        "province_code": "NW",
        "country_code": "DE",
        "vat_in": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "whitelabel_address": null,
    "transactions": [],
    "fulfillments": [],
    "id_tags": []
}

Shipping Rates

To be able to send the order, it is necessary to query the shipping rates and select the appropriate shipping method. This happens asynchronously and you have to use Polling or Webhooks.

If the response is 200 OK, you have to update the shipping_line in the checkout with the desired shipment handle.

Example

{primary.fa-paper-plane} Request

GET /checkouts/1/shipping-rates HTTP/1.1

{success} Response

HTTP/1.1 202 Accepted
Location https://api.smake.io/jobs/1

{primary.fa-paper-plane} Request as soon as the task is completed

GET /checkouts/1/shipping-rates HTTP/1.1

{success} Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "is_test": true,
            "order_id": 1,
            "handle": "pickup",
            "title": "Abholung",
            "price": 22
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": 15,
        "to": 1
    }
}

{warning} Webhook Payloads always have all shipping rates, so the pagination is not available.

Update

During the process it is possible to update the checkout.

{warning} If you change shipping_address afterwards, you have to request the shipping ratess again and update the shipping_line.

Examples

{primary.fa-paper-plane} Request to update the items

PUT /checkouts/1 HTTP/1.1

{
    "items": [
        {
            "variant_id": 3,
            "quantity": 1
        },
        {
             "variant_id": 4,
             "quantity": 5
        }
    ]
}

{success} Response

HTTP/1.1 200 OK

{
    ...
    "items": [
        {
            "id": 77,
            "quantity": 1,
            ...
            "variant": {
                "id": 3,
                ...
            },
        },
        {
            "id": 78,
            "quantity": 5,
            ...
            "variant": {
                "id": 4,
                ...
            },
        }
    ],
    ...
}

{primary.fa-paper-plane} Request to update the shipping_line

PUT /checkouts/1 HTTP/1.1

{
    "shipping": {
        "handle": "pickup"
    }
}

{success} Response

HTTP/1.1 200 OK

{
    ...
    "shipping_line": {
        "title": "Pickup",
        "price": 22.06,
        "total": 26.25,
        "tax": 4.19
    },
    ...
}

Complete

To complete the purchase, the payment.handle must be transferred. The payment.handle parameter accepts all handles that are listed within endpoint payment-methods.

You can then use the orders endpoint to list and filter your orders.

Example

{primary.fa-paper-plane} Request to complete a checkout

PUT /checkouts/1/complete HTTP/1.1

{
    "payment": {
      "handle": "invoice",
    }
}