# PostPromotionCodes From **Stripe API**. `POST /v1/promotion_codes`

A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.

## Request body - Required: true ### `application/x-www-form-urlencoded` - Type: `object` ```json {"additionalProperties":false,"properties":{"active":{"description":"Whether the promotion code is currently active.","type":"boolean"},"code":{"description":"The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. If left blank, we will generate one automatically.","maxLength":500,"type":"string"},"coupon":{"description":"The coupon for this promotion code.","maxLength":5000,"type":"string"},"customer":{"description":"The customer that this promotion code can be used by. If not set, the promotion code can be used by all customers.","maxLength":5000,"type":"string"},"expand":{"description":"Specifies which fields in the response should be expanded.","items":{"maxLength":5000,"type":"string"},"type":"array"},"expires_at":{"description":"The timestamp at which this promotion code will expire. If the coupon has specified a `redeems_by`, then this value cannot be after the coupon's `redeems_by`.","format":"unix-time","type":"integer"},"max_redemptions":{"description":"A positive integer specifying the number of times the promotion code can be redeemed. If the coupon has specified a `max_redemptions`, then this value cannot be greater than the coupon's `max_redemptions`.","type":"integer"},"metadata":{"additionalProperties":{"type":"string"},"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.","type":"object"},"restrictions":{"description":"Settings that restrict the redemption of the promotion code.","properties":{"first_time_transaction":{"type":"boolean"},"minimum_amount":{"type":"integer"},"minimum_amount_currency":{"type":"string"}},"title":"restrictions_params","type":"object"}},"required":["coupon"],"type":"object"} ``` ## Security ### `basicAuth` - Type: `http` - Request header: `Authorization` - Scheme: `basic` Send credentials in the `Authorization` request header using the `Basic` scheme. Basic HTTP authentication. Allowed headers-- Authorization: Basic | Authorization: Basic ### `bearerAuth` - Type: `http` - Request header: `Authorization` - Scheme: `bearer` - Bearer format: `auth-scheme` Send the token in the `Authorization` request header using the `Bearer` scheme. Bearer HTTP authentication. Allowed headers-- Authorization: Bearer ## Responses ### `200` Successful response. ### `application/json` - Type: `object` A Promotion Code represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon. ```json {"description":"A Promotion Code represents a customer-redeemable code for a coupon. It can be used to\ncreate multiple codes for a single coupon.","properties":{"active":{"description":"Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.","type":"boolean"},"code":{"description":"The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer.","maxLength":5000,"type":"string"},"coupon":{"$ref":"#/components/schemas/coupon"},"created":{"description":"Time at which the object was created. Measured in seconds since the Unix epoch.","format":"unix-time","type":"integer"},"customer":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/customer"},{"$ref":"#/components/schemas/deleted_customer"}],"description":"The customer that this promotion code can be used by.","nullable":true,"x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/customer"},{"$ref":"#/components/schemas/deleted_customer"}]}},"expires_at":{"description":"Date at which the promotion code can no longer be redeemed.","format":"unix-time","nullable":true,"type":"integer"},"id":{"description":"Unique identifier for the object.","maxLength":5000,"type":"string"},"livemode":{"description":"Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.","type":"boolean"},"max_redemptions":{"description":"Maximum number of times this promotion code can be redeemed.","nullable":true,"type":"integer"},"metadata":{"additionalProperties":{"maxLength":500,"type":"string"},"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.","nullable":true,"type":"object"},"object":{"description":"String representing the object's type. Objects of the same type share the same value.","enum":["promotion_code"],"type":"string"},"restrictions":{"$ref":"#/components/schemas/promotion_codes_resource_restrictions"},"times_redeemed":{"description":"Number of times this promotion code has been used.","type":"integer"}},"required":["active","code","coupon","created","id","livemode","object","restrictions","times_redeemed"],"title":"PromotionCode","type":"object","x-expandableFields":["coupon","customer","restrictions"],"x-resourceId":"promotion_code"} ``` ### `default` Error response. ### `application/json` - Type: `object` An error response from the Stripe API ```json {"description":"An error response from the Stripe API","properties":{"error":{"$ref":"#/components/schemas/api_errors"}},"required":["error"],"type":"object"} ``` ## Request examples ### cURL ```shell curl --request POST \ --url https://api.stripe.com/v1/promotion_codes \ --header 'content-type: application/x-www-form-urlencoded' \ --data '{ "active": true, "code": "string", "coupon": "string", "customer": "string", "expand": [ "string" ], "expires_at": 1, "max_redemptions": 1, "metadata": {}, "restrictions": { "first_time_transaction": true, "minimum_amount": 1, "minimum_amount_currency": "string" } }' ```