---
updatedAt: 2026-07-17T21:11:16.000Z
agentTools:
  projectIndex: https://hub.locally.com/llms.txt
---

# Commit order

Retrieve a validated cart and commit the order for processing.

## Request Parameters

*🏷️ header · unmarked parameters are query params*

| Parameter               | Type   | Required | Description                                                                      |
| ----------------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `Locally-Api-Token` 🏷️ | string | Yes      | Locally API token must be passed in the header to authenticate the API consumer. |
| `Locally-Pl-Jwt` 🏷️    | string | No       | JSON Web Token passed in the header to identify the user. Does not expire.       |

## Example Request

```curl cURL
curl 'https://www.locally.com/headless/api/1.0/cart/commit' \
--request POST \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Pl-Jwt: {{CART_HASH_JWT}}'
```
```javascript JavaScript
const response = await fetch('https://www.locally.com/headless/api/1.0/cart/commit', {
  method: 'POST',
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}',
    'Locally-Pl-Jwt': '{{CART_HASH_JWT}}'
  }
});
const data = await response.json();
```
```python Python
import requests

url = "https://www.locally.com/headless/api/1.0/cart/commit"

headers = {
    "Locally-Api-Token": "{{API_TOKEN}}",
    "Locally-Pl-Jwt": "{{CART_HASH_JWT}}"
}

response = requests.post(url, headers=headers)
data = response.json()
```

The request takes no body. The cart to commit is identified by the `Locally-Pl-Jwt` header — pass the `cart_hash_jwt` value returned by a successful `/headless/api/1.0/cart/validate` response.

## Example Response

```json JSON
{
  "success": true,
  "data": {
    "message": "Your order has been placed",
    "target_uri": "/order/QE3QL6/UQP778",
    "is_test": 0,
    "status_code": 200,
    "cart_hash": "QE3QL6",
    "store_uri": "/order/QE3QL6/SKP2GH",
    "session": {
      "id": "vD2kq9mXw4bT7nR5cJ1sL8fA3gH6pZ0yE2uN4iK9"
    }
  },
  "msg": ""
}
```

## Response Explanation

* `success` — Boolean outcome of the call. When `false`, the response also carries a top-level `error_code` and explanatory `msg` — always check `success`, not just the HTTP status.
* `data.message` — Shopper-facing order outcome (here `Your order has been placed`). Placing an order does not capture funds — in most cases Locally captures only after the store confirms stock.
* `data.target_uri` — Relative URI of the shopper's order status page on locally.com, built from the cart hash and a buyer-only secret. Send the shopper here to track the order.
* `data.is_test` — `0` for live carts, `1` for carts created with a `test_*` API key — test carts use a decoy payment provider and are invisible to retailers. See [Testing Your Integration](https://hub.locally.com/lcly/docs/testing-your-integration).
* `data.status_code` — HTTP-style result of order processing duplicated inside the payload; `200` means the order was placed. Failures surface as a non-200 HTTP response with an error envelope instead.
* `data.cart_hash` — Unique short identifier for the cart. Other endpoints accept it as the `hash` parameter, and it appears in order URIs.
* `data.store_uri` — Retailer-scoped order link built with the store's secret. Returned only when your API token has the `Retailer Secret Link` permission.
* `data.session.id` — Locally session ID, returned on every response. Replay it via the `Locally-Api-Session-Id` header to persist the shopper's session between calls; expired IDs are transparently replaced with fresh ones.
* `msg` — Human-readable error text; empty string on success. In production, unexpected server errors are masked as `App server error` with a `lookup` reference — see [Handling Errors in Production](https://hub.locally.com/lcly/docs/handling-errors-in-production).

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "External Headless API",
    "description": "Welcome to Locally's Headless API documentation. With our Headless API.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://www.locally.com"
    }
  ],
  "paths": {
    "/headless/api/1.0/cart/commit": {
      "post": {
        "tags": [
          "Cart"
        ],
        "summary": "Commit order",
        "description": "Retrieve a validated cart and commit the order for processing.",
        "operationId": "HeadlessAPIController::cart_commit",
        "parameters": [
          {
            "name": "Locally-Api-Token",
            "in": "header",
            "description": "Locally API token must be passed in the header to authenticate the API consumer",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Locally-Pl-Jwt",
            "in": "header",
            "description": "JSON Web Token passed in the header to identify the user. Does not expire.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful"
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "402": {
            "description": "Request Failed"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          },
          "429": {
            "description": "Too Many Requests"
          },
          "500": {
            "description": "Server Error"
          }
        },
        "security": [
          {
            "HeaderAuthentication": []
          }
        ]
      }
    }
  }
}
```