# Complete a cart

URL: https://docs.sparklayer.io/developers/api/ordering/complete-cart
Operation: `POST /api/v1/carts/{id}/complete` (operationId `completeCart`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ordering.yaml

Places the order: checks the shipping rate and payment method, creates a purchase, deletes the cart and returns the new `purchase_id` with a `201`. If the cart has validation errors you haven't listed in `ignore_validation_errors` (use `"*"` to ignore all of them), you get a `422` (`cart-validation-errors`) and no order is created. Because the cart is deleted once the order is placed, repeating the call returns `404`.

`POST /api/v1/carts/{id}/complete`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl -X POST "https://app.sparklayer.io/api/v1/carts/9151f21f-43ae-43b4-92f3-f4af67cdf544/complete" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_rate_handle": "<shipping_rate_handle>",
  "payment_method": "paymentByInvoice",
  "ignore_validation_errors": [
    "maximum-order-item-quantity"
  ]
}'
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The cart's ID: the `cart_id` returned by **Create a cart**. Example: `9151f21f-43ae-43b4-92f3-f4af67cdf544` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shipping_rate_handle` | string | Yes | The `handle` of one of the shipping methods returned by **Calculate a cart**. |
| `payment_method` | "paymentByInvoice" \| "paymentOnAccount" | Yes | How the customer pays for the order. |
| `ignore_validation_errors` | ("maximum-order-item-quantity" \| "maximum-order-totals" \| "maximum-parent-quantity" \| "maximum-variant-quantity" \| "minimum-order-item-quantity" \| "minimum-order-totals" \| "minimum-parent-quantity" \| "minimum-variant-quantity" \| "pack-size" \| "pricing-unavailable" \| "pricing-unavailable-for-selected-qty" \| "quantity-unavailable" \| "*")[] | Yes | Specify which validation errors to ignore and allow the cart to complete checkout. Passing "*" will ignore all validation errors. |

```json
{
  "shipping_rate_handle": "<shipping_rate_handle>",
  "payment_method": "paymentByInvoice",
  "ignore_validation_errors": [
    "maximum-order-item-quantity"
  ]
}
```

### Responses

#### 201: The order was placed: `purchase_id` is the new purchase.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `purchase_id` | string \| null | | |

```json
{
  "purchase_id": "<purchase_id>"
}
```

#### 404: Cart not found

#### 422: The cart can't be completed: a `cart-error` (such as an unavailable payment method or shipping rate) or `cart-validation-errors` problem. See [Cart errors](https://docs.sparklayer.io/developers/errors.md#cart-errors).

One of these:

**CartErrorResponse**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | 422 | | HTTP Status code returned from API |
| `title` | "cart-error" | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | "cart-shipping-rate-handle-unavailable" \| "cart-customer-not-found" \| "cart-impersonator-user-not-found" \| "cart-payment-method-unavailable" | | Machine-readable error code |

**CartValidationErrorResponse**: Structure for returning error responses as a result of cart validation errors occurring.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | |
| `status` | 422 | | |
| `title` | "cart-validation-errors" | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].validation_error_types` | ("maximum-order-item-quantity" \| "maximum-order-totals" \| "maximum-parent-quantity" \| "maximum-variant-quantity" \| "minimum-order-item-quantity" \| "minimum-order-totals" \| "minimum-parent-quantity" \| "minimum-variant-quantity" \| "pack-size" \| "pricing-unavailable" \| "pricing-unavailable-for-selected-qty" \| "quantity-unavailable")[] | | |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

- **Error**: the standard error body (below).

```json
{
  "detail": "Cart error occurred",
  "status": 422,
  "title": "cart-error",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "cart-shipping-rate-handle-unavailable"
    }
  ]
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string \| null | | |
| `errors` | object[] \| null | | A list of errors related to the call |
| `errors[].code` | string | | Machine-readable error code |
| `errors[].property` | string | | The property the error relates to |
| `errors[].message` | string | | Human readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/api/errors#invalid-api-request-contents",
  "errors": [
    {
      "code": "resource-not-found",
      "property": "stock_location_id",
      "message": "stock_location_id not found"
    }
  ]
}
```