Stripe Coupon API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Coupon API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Coupon
paths:
  /v1/coupons/{coupon}:
    delete:
      description: <p>You can delete coupons via the <a href="https://dashboard.stripe.com/coupons">coupon management</a> page of the Stripe dashboard. However, deleting a coupon does not affect any customers who have already applied the coupon; it means that new customers can’t redeem the coupon. You can also delete coupons via the API.</p>
      operationId: deleteCouponsCoupon
      parameters:
      - in: path
        name: coupon
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/DeleteCouponsCouponRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleted_coupon'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Delete   Coupons Coupon
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        PullTagsFromSummary: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Coupon
    get:
      description: <p>Retrieves the coupon with the given ID.</p>
      operationId: getCouponsCoupon
      parameters:
      - in: path
        name: coupon
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCouponsCouponRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/coupon'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Coupons Coupon
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        PullTagsFromSummary: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Coupon
    post:
      description: <p>Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.</p>
      operationId: postCouponsCoupon
      parameters:
      - in: path
        name: coupon
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              currency_options:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostCouponsCouponRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/coupon'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Coupons Coupon
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        PullTagsFromSummary: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Coupon
components:
  schemas:
    PostCouponsCouponRequest:
      type: object
      properties:
        currency_options:
          additionalProperties:
            properties:
              amount_off:
                type: integer
            required:
            - amount_off
            title: currency_option
            type: object
          description: Coupons defined in each available currency option (only supported if the coupon is amount-based). Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
          type: object
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - enum:
            - ''
            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`.
        name:
          description: Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the `id` is shown if `name` is not set.
          maxLength: 40
          type: string
    GetCouponsCouponRequest:
      type: object
      properties: {}
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    coupon:
      description: 'A coupon contains information about a percent-off or amount-off discount you

        might want to apply to a customer. Coupons may be applied to [subscriptions](https://stripe.com/docs/api#subscriptions), [invoices](https://stripe.com/docs/api#invoices),

        [checkout sessions](https://stripe.com/docs/api/checkout/sessions), [quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge) or [payment intents](https://stripe.com/docs/api/payment_intents).'
      properties:
        amount_off:
          description: Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.
          nullable: true
          type: integer
        applies_to:
          $ref: '#/components/schemas/coupon_applies_to'
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        currency:
          description: If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.
          nullable: true
          type: string
        currency_options:
          additionalProperties:
            $ref: '#/components/schemas/coupon_currency_option'
          description: Coupons defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
          type: object
        duration:
          description: One of `forever`, `once`, and `repeating`. Describes how long a customer who applies this coupon will get the discount.
          enum:
          - forever
          - once
          - repeating
          type: string
          x-stripeBypassValidation: true
        duration_in_months:
          description: If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.
          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 coupon can be redeemed, in total, across all customers, before it is no longer valid.
          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
        name:
          description: Name of the coupon displayed to customers on for instance invoices or receipts.
          maxLength: 5000
          nullable: true
          type: string
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - coupon
          type: string
        percent_off:
          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 $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.
          nullable: true
          type: number
        redeem_by:
          description: Date after which the coupon can no longer be redeemed.
          format: unix-time
          nullable: true
          type: integer
        times_redeemed:
          description: Number of times this coupon has been applied to a customer.
          type: integer
        valid:
          description: Taking account of the above properties, whether this coupon can still be applied to a customer.
          type: boolean
      required:
      - created
      - duration
      - id
      - livemode
      - object
      - times_redeemed
      - valid
      title: Coupon
      type: object
      x-expandableFields:
      - applies_to
      - currency_options
      x-resourceId: coupon
    DeleteCouponsCouponRequest:
      type: object
      properties: {}
    deleted_coupon:
      description: ''
      properties:
        deleted:
          description: Always true for a deleted object
          enum:
          - true
          type: boolean
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - coupon
          type: string
      required:
      - deleted
      - id
      - object
      title: DeletedCoupon
      type: object
      x-expandableFields: []
      x-resourceId: deleted_coupon