---
title: "Record order"
description: "Records an order paid outside the store, granting what it bought."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Record order

Needs the transaction:write scope.

## Call

- Tool: `record_order`
- Scope: `transaction:write`
- Writes, adding without changing what is there.
- Acts on a store.

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `store` | `string` | No | The store to act on. |
| `customer` | `object` | Yes | By id, or by email: whoever the address reaches, else its invited customer. |
| `currency` | `string` | Yes |  |
| `items` | `array of object` | Yes |  |
| `source_key` | `string or null` | No | The writer's own id for the sale, so a retried record is not a second order. |
| `note` | `string or null` | No | Shown to the customer with their order. |
| `occurred_at` | `string or null` | No |  |
| `grants` | `boolean` | No | Whether each line grants its product from when the sale occurred; on unless said otherwise. |

```json
{
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "description": "The store to act on."
    },
    "customer": {
      "description": "By id, or by email: whoever the address reaches, else its invited customer.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          "required": [
            "id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "minLength": 1,
              "maxLength": 254,
              "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
            }
          },
          "required": [
            "email"
          ],
          "additionalProperties": false
        }
      ]
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "pattern": "^[A-Za-z]{3}$"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "slug"
                ],
                "additionalProperties": false
              }
            ]
          },
          "tier": {
            "description": "The tier sold; the price's own when a price is named.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "price": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "amount": {
            "type": "integer",
            "minimum": 0
          },
          "discount": {
            "description": "At most the line's amount.",
            "type": "integer",
            "minimum": 0
          },
          "code": {
            "description": "The discount code the line sold with, so a rule bound to it fires.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  }
                },
                "required": [
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "product",
          "amount"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 100
    },
    "source_key": {
      "description": "The writer's own id for the sale, so a retried record is not a second order.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "note": {
      "description": "Shown to the customer with their order.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "occurred_at": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,3})?)?(Z|[+-]\\d{2}:\\d{2}))?$"
        },
        {
          "type": "null"
        }
      ]
    },
    "grants": {
      "description": "Whether each line grants its product from when the sale occurred; on unless said otherwise.",
      "type": "boolean"
    }
  },
  "required": [
    "customer",
    "currency",
    "items"
  ],
  "additionalProperties": false
}
```

## Answer

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `refunds_refused` | `array of object` | Yes |  |
| `customer` | `object or null` | Yes |  |
| `settled` | `number or null` | Yes |  |
| `refunded` | `number or null` | Yes |  |
| `revocable` | `boolean` | Yes | Whether a revocation of the order would end anything: its customer's grants or running subscriptions on its products, or its guests' tickets. |
| `revocation` | `object or null` | Yes | The latest revocation of its access for cause; null while none. |
| `failed_revocations` | `object` | Yes |  |
| `refund_status` | `string or null` | Yes | How much of what it settled came back: none, part or all of it; null while it settled and refunded nothing, or withheld. |
| `lines` | `object` | Yes |  |
| `settlements` | `object` | Yes |  |
| `refunds` | `object` | Yes |  |
| `affiliates` | `object` | Yes |  |
| `id` | `string` | Yes |  |
| `number` | `number` | Yes |  |
| `customer_id` | `string or null` | Yes |  |
| `currency` | `string` | Yes |  |
| `exponent` | `number or null` | Yes |  |
| `amount` | `number or null` | Yes |  |
| `discount` | `number or null` | Yes |  |
| `total` | `number or null` | Yes |  |
| `free` | `boolean` | Yes |  |
| `fees` | `number or null` | Yes |  |
| `source` | `string` | Yes |  |
| `source_key` | `string or null` | Yes |  |
| `statements` | `object` | Yes |  |
| `note` | `string or null` | Yes |  |
| `occurred_at` | `string or null` | Yes |  |
| `recorded_at` | `string or null` | Yes |  |

The answer's full shape is on [its API reference page](/merchant-api/reference/record-order).

## Errors

A refused call is a tool error. Its `structuredContent` holds a `code` and its `context`, except for `client-fault`. This tool may answer:

- `invalid`: an argument is malformed; `context.path` names it.
- `invalid` at `["store"]`: `store` is missing while the connection reaches more than one store, or names a store it doesn't reach.
- `not_found`: nothing matches a reference given.
- `conflict`: the call clashes with the current state; `context` names the field and, where it helps, its current value, and for a `from`, `live`, `expect` or version that no longer matches, the argument (`path`) and what it takes (`reason`).
- `not_permitted`: this connection may not make this call. When `context.reason` is `limit`, too many calls: `retry_after` says when to try again.
- `internal` or `unavailable`: the call failed inside Sherpo, and the write may have landed. If you sent a `source_key`, send the same one again: a `conflict` at `source_key` then means the first call landed, and `current` names its order. The key is checked before the order's fields, so this holds even when the customer, currency or lines changed since; read that order back to check it is the same sale. Without one, read the state back before trying again.
- `client-fault`: the server failed around the call. `core_answer` `ok` means the write landed, so don't send it again. When `reached_core` is false, nothing happened and the call may be made again. Otherwise, if you sent a `source_key`, send the same one again: a `conflict` at `source_key` then means the first call landed, and `current` names its order. The key is checked before the order's fields, so this holds even when the customer, currency or lines changed since; read that order back to check it is the same sale. Without one, read the state back before trying again.
- HTTP 403 with `insufficient_scope`: the connection lacks the scope this tool needs.
- HTTP 401 with `invalid_token`: the access token expired or the connection ended. Refresh the token, and connect again if the refresh fails or the new token is refused too.

Any other code may come back too, such as a `conflict` when the state changed under the call. When the answer was already streaming, a 401 or 403 comes back as a tool error with only its text. See [Errors](/merchant-mcp/errors) for every code and its context.

Source: https://docs.sherpo.io/merchant-mcp/tools/record_order/index.mdx
