# Create a promotion code ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/promotion_code: post: summary: Create a promotion code deprecated: false description: >- A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date. tags: - API Reference/Promotion Code parameters: - name: Accept in: header description: '' required: true example: application/json schema: type: string - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object properties: coupon: type: string description: The coupon for this promotion code. code: type: string 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. metadata: type: object properties: {} description: >- Set of key-value pairs 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. x-apifox-orders: [] x-apifox-ignore-properties: [] active: type: boolean description: Whether the promotion code is currently active. customer: type: string description: >- The customer that this promotion code can be used by. If not set, the promotion code can be used by all customers. expires_at: type: string 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. max_redemptions: type: integer 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. restrictions: type: object properties: first_time_transaction: type: boolean description: >- A Boolean indicating if the Promotion Code should only be redeemed for Customers without any successful payments or invoices minimum_amount: type: integer description: >- Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work). minimum_amount_currency: type: string description: Three-letter ISO code for minimum_amount x-apifox-orders: - first_time_transaction - minimum_amount - minimum_amount_currency description: Settings that restrict the redemption of the promotion code. x-apifox-ignore-properties: [] x-apifox-orders: - coupon - code - metadata - active - customer - expires_at - max_redemptions - restrictions required: - coupon x-apifox-ignore-properties: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Promotion%20Code' headers: {} x-apifox-name: OK security: - basic: [] x-apifox-folder: API Reference/Promotion Code x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/1296482/apis/api-159875133-run components: schemas: Promotion Code: type: object properties: id: type: string description: Unique identifier for the object. object: type: string description: >- String representing the object’s type. Objects of the same type share the same value. active: type: boolean description: >- Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. code: type: string description: >- The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. coupon: description: Hash describing the coupon for this promotion code. $ref: '#/components/schemas/Coupons' created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. customer: type: 'null' description: The customer that this promotion code can be used by. expires_at: type: 'null' description: Date at which the promotion code can no longer be redeemed. livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. max_redemptions: type: 'null' description: Maximum number of times this promotion code can be redeemed. metadata: type: object properties: {} x-apifox-orders: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] restrictions: type: object properties: first_time_transaction: type: boolean description: >- A Boolean indicating if the Promotion Code should only be redeemed for Customers without any successful payments or invoices minimum_amount: type: 'null' description: >- Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work). minimum_amount_currency: type: 'null' description: Three-letter ISO code for minimum_amount x-apifox-orders: - first_time_transaction - minimum_amount - minimum_amount_currency description: Settings that restrict the redemption of the promotion code. x-apifox-ignore-properties: [] times_redeemed: type: integer description: Number of times this promotion code has been used. x-apifox-orders: - id - object - active - code - coupon - created - customer - expires_at - livemode - max_redemptions - metadata - restrictions - times_redeemed x-apifox-ignore-properties: [] x-apifox-folder: '' Coupons: type: object properties: id: type: string description: Unique identifier for the object. amount_off: type: integer description: >- Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer. nullable: true currency: type: string description: >- If amount_off has been set, the three-letter ISO code for the currency of the amount to take off. nullable: true duration: type: string description: >- One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount. enum: - forever - once - repeating x-apifox-enum: - value: forever name: '' description: >- Applies to all charges from a subscription with this coupon applied. - value: once name: '' description: >- Applies to the first charge from a subscription with this coupon applied. - value: repeating name: '' description: >- Applies to charges in the first duration_in_months months from a subscription with this coupon applied. duration_in_months: type: integer description: >- Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect. duration_in_weeks: type: string description: >- Required only if duration is repeating, in which case it must be a positive integer that specifies the number of weeks the discount will be in effect. duration_in_days: type: string description: >- Required only if duration is repeating, in which case it must be a positive integer that specifies the number of weeks the discount will be in effect. object: type: string description: >- String representing the object’s type. Objects of the same type share the same value. created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. metadata: type: object properties: {} x-apifox-orders: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] name: type: string description: >- Name of the coupon displayed to customers on for instance invoices or receipts. percent_off: type: number description: >- Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead. nullable: true max_redemptions: type: integer description: >- Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid. nullable: true redeem_by: type: integer description: Date after which the coupon can no longer be redeemed. nullable: true times_redeemed: type: integer description: Number of times this coupon has been applied to a customer. valid: type: boolean description: >- Taking account of the above properties, whether this coupon can still be applied to a customer. applies_to: type: object properties: products: type: array items: type: string description: A list of product IDs this coupon applies to description: Contains information about what this coupon applies to. x-apifox-orders: - products x-apifox-ignore-properties: [] currency_options: type: object properties: .amount_off: type: integer description: >- Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer. description: >- Coupons defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency. x-apifox-orders: - .amount_off x-apifox-ignore-properties: [] x-apifox-orders: - id - amount_off - currency - duration - duration_in_months - duration_in_weeks - duration_in_days - object - created - livemode - metadata - name - percent_off - max_redemptions - redeem_by - times_redeemed - valid - applies_to - currency_options required: - duration_in_weeks - duration_in_days x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: basic: type: http scheme: basic servers: - url: https://apitest.wooshpay.com description: 官网测试 security: - basic: [] ```