> ## Documentation Index > Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a promotion > Updates a promotion. The `rules` and `actions` arrays are treated as a *desired set* — rows with `id` update in place, rows without `id` are built fresh, and any existing row not present in the array is destroyed. Pass `rules: []` or `actions: []` to clear them. **Required scope:** `write_promotions` (for API-key authentication). ## OpenAPI ````yaml /api-reference/admin.yaml patch /api/v3/admin/promotions/{id} openapi: 3.0.3 info: title: Admin API contact: name: Spree Commerce url: https://spreecommerce.org email: hello@spreecommerce.org description: > Spree Admin API v3 - Administrative API for managing products, orders, and store settings. ## Authentication The Admin API requires a secret API key passed in the `x-spree-api-key` header. Secret API keys can be generated in the Spree admin dashboard. ## Response Format All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys. Single resource endpoints return a flat JSON object. ## Resource IDs Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`, `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths, request bodies, and Ransack filters all accept them directly. ## Error Handling Errors return a consistent format: ```json { "error": { "code": "validation_error", "message": "Validation failed", "details": { "name": ["can't be blank"] } } } ``` version: v3 servers: - url: http://{defaultHost} variables: defaultHost: default: localhost:3000 security: [] tags: - name: Authentication description: Admin user authentication - name: Product Catalog description: Products, variants, and option types - name: Orders description: >- Order management — orders, items, payments, fulfillments, refunds, gift cards, store credits - name: Customers description: Customer management — profiles, addresses, store credits, credit cards - name: Configuration description: Store configuration — payment methods, tag autocomplete paths: /api/v3/admin/promotions/{id}: patch: tags: - Promotions summary: Update a promotion description: |- Updates a promotion. The `rules` and `actions` arrays are treated as a *desired set* — rows with `id` update in place, rows without `id` are built fresh, and any existing row not present in the array is destroyed. Pass `rules: []` or `actions: []` to clear them. **Required scope:** `write_promotions` (for API-key authentication). parameters: - name: x-spree-api-key in: header required: true schema: type: string - name: Authorization in: header required: true schema: type: string - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string nullable: true code: type: string nullable: true starts_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true usage_limit: type: integer nullable: true match_policy: type: string enum: - all - any kind: type: string enum: - coupon_code - automatic promotion_category_id: type: string nullable: true rules: type: array items: type: object properties: id: type: string nullable: true description: >- Pass to update an existing rule; omit to build a new one type: type: string example: currency preferences: type: object additionalProperties: true product_ids: type: array items: type: string category_ids: type: array items: type: string customer_ids: type: array items: type: string required: - type actions: type: array items: type: object properties: id: type: string nullable: true type: type: string example: free_shipping preferences: type: object additionalProperties: true calculator: type: object properties: type: type: string example: flat_percent_item_total preferences: type: object additionalProperties: true required: - type responses: '200': description: rules and actions cleared with empty arrays content: application/json: example: id: promo_UkLWZg9DAJ name: Summer Sale description: null code: summer starts_at: '2026-06-05T13:13:03.976Z' expires_at: null usage_limit: null match_policy: all path: null kind: coupon_code multi_codes: false number_of_codes: null code_prefix: null promotion_category_id: null metadata: {} created_at: '2026-06-05T13:13:03.977Z' updated_at: '2026-06-05T13:13:04.254Z' action_ids: [] rule_ids: [] security: - api_key: [] bearer_auth: [] x-codeSamples: - lang: javascript label: Spree Admin SDK source: |- import { createAdminClient } from '@spree/admin-sdk' const client = createAdminClient({ baseUrl: 'https://your-store.com', secretKey: 'sk_xxx', }) // Basic field update await client.promotions.update(promotionId, { description: 'Updated description', }) // One-shot: rewrite rules + actions in a single request await client.promotions.update(promotionId, { name: 'Holiday Sale', rules: [ // Update an existing rule by id — `preferences` overwrite the prior set { id: 'prorule_existing', type: 'currency', preferences: { currency: 'EUR' }, }, // Add a new rule { type: 'item_total', preferences: { amount_min: 50, operator_min: 'gte' }, }, ], actions: [ // Swap calculator type on an existing action { id: 'proaction_existing', type: 'create_item_adjustments', calculator: { type: 'percent_on_line_item', preferences: { percent: 15 }, }, }, ], }) // Remove all rules/actions await client.promotions.update(promotionId, { rules: [], actions: [], }) components: securitySchemes: api_key: type: apiKey name: x-spree-api-key in: header description: Secret API key for admin access bearer_auth: type: http scheme: bearer bearerFormat: JWT description: JWT token for admin user authentication ````