Checkouts

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


Create

Attribute

Field Type Description Required
project_name string Project name
external_identifier string The external identifier is an optional field for the order id for your system. The external identifier must be unique.
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: 'NW' (North Rhine-Westphalia), 'AL' (Alabama) yes
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",
   "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,
    "project_name": null,
    "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,
            "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
    }
}

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

In order to complete the checkout, the following must be transferred as payment.handle invoice. and the request must contain the total amount of the order.

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",
      "amount": 150.0
    }
}