# Get a promotion code

> The promotion_codes.get operation: GET /api/v1/promotion_codes/{id} in the REST API and the promotion_codes_get tool in the MCP server.

Returns one promotion code of the brand in the request's mode, archived or not, with its restrictions and how often it was redeemed. To find a code by what customers type, use `promotion_codes.list` with `code`.

## At a glance

- **REST:** `GET /api/v1/promotion_codes/{id}`
- **MCP tool:** `promotion_codes_get`
- **Operation ID:** `promotion_codes.get`
- **Scope:** Brand
- **Permission:** `catalog:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `catalog:read` scope
- **Since:** M5

## Request

### Path parameters

| Field | Type         | Description |
| ----- | ------------ | ----------- |
| `id`  | `promo_…` ID |             |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field                         | Type               | Description                                    |
| ----------------------------- | ------------------ | ---------------------------------------------- |
| `id`                          | `promo_…` ID       |                                                |
| `object`                      | `"promotion_code"` |                                                |
| `brandId`                     | `brd_…` ID         |                                                |
| `livemode`                    | boolean            |                                                |
| `couponId`                    | `cpn_…` ID         |                                                |
| `code`                        | string             | As entered; customers may type it in any case. |
| `restrictions`                | object             |                                                |
| `restrictions.firstTimeOnly`  | boolean            |                                                |
| `restrictions.minimumAmount`  | money or null      |                                                |
| `restrictions.customerId`     | string or null     |                                                |
| `restrictions.expiresAt`      | date-time or null  |                                                |
| `restrictions.maxRedemptions` | integer or null    |                                                |
| `timesRedeemed`               | integer            |                                                |
| `active`                      | boolean            |                                                |
| `metadata`                    | object             |                                                |
| `createdAt`                   | date-time          |                                                |
| `updatedAt`                   | date-time          |                                                |

## Examples

### A launch code

```http
GET /api/v1/promotion_codes/promo_01m4tx5nj8emwbyf7y9vcf47z2
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "id": "promo_01m4tx5nj8emwbyf7y9vcf47z2",
  "object": "promotion_code",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "couponId": "cpn_01m4tx5nj8emwbyf7y9vcf47z0",
  "code": "LAUNCH50",
  "restrictions": {
    "firstTimeOnly": true,
    "minimumAmount": null,
    "customerId": null,
    "expiresAt": null,
    "maxRedemptions": 200
  },
  "timesRedeemed": 0,
  "active": true,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                      | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No promotion code with this ID is visible to the request. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | You can't see this brand's catalog.                       | Ask an organization owner or admin for a role or scope that allows this action.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).