WooCommerce Coupons API

openapi: 3.2.0
info:
  title: WooCommerce REST Coupons API
  description: The WooCommerce REST API is the primary server-side interface for reading and writing WooCommerce store data programmatically.
  version: v3
  contact:
    name: WooCommerce Developer Support
    url: https://developer.woocommerce.com/docs/apis/rest-api/
  termsOfService: https://woocommerce.com/terms-conditions/
servers:
- url: https://example.com/wp-json/wc/v3
  description: Production Server (replace example.com with your store domain)
security:
- basicAuth: []
tags:
- name: Coupons
  description: Create, retrieve, update, and delete discount coupons
paths:
  /coupons:
    get:
      operationId: listCoupons
      summary: WooCommerce List All Coupons
      description: Returns a paginated list of all coupons. Can be filtered by coupon code, discount type, date ranges, and sorted by various fields.
      tags:
      - Coupons
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/after'
      - $ref: '#/components/parameters/before'
      - name: code
        in: query
        description: Filter coupons by coupon code.
        required: false
        schema:
          type: string
        example: string-value
      responses:
        '200':
          description: List of coupons
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Coupon'
              examples:
                listCoupons200Example:
                  summary: Default listCoupons 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    code: string-value
                    amount: string-value
                    discount_type: percent
                    description: A sample description
                    date_expires: '2026-05-03T14:30:00Z'
                    usage_count: 1
                    individual_use: true
                    product_ids:
                    - 1
                    excluded_product_ids:
                    - 1
                    usage_limit: 1
                    usage_limit_per_user: 1
                    minimum_amount: string-value
                    maximum_amount: string-value
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCoupon
      summary: WooCommerce Create a Coupon
      description: Creates a new discount coupon. Requires a coupon code. Supports percentage, fixed cart, and fixed product discount types with optional usage limits, expiry dates, and product or category restrictions.
      tags:
      - Coupons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponInput'
      responses:
        '201':
          description: Coupon created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
              examples:
                createCoupon201Example:
                  summary: Default createCoupon 201 response
                  x-microcks-default: true
                  value:
                    id: 1
                    code: string-value
                    amount: string-value
                    discount_type: percent
                    description: A sample description
                    date_expires: '2026-05-03T14:30:00Z'
                    usage_count: 1
                    individual_use: true
                    product_ids:
                    - 1
                    excluded_product_ids:
                    - 1
                    usage_limit: 1
                    usage_limit_per_user: 1
                    minimum_amount: string-value
                    maximum_amount: string-value
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    meta_data:
                    - string-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /coupons/{id}:
    get:
      operationId: getCoupon
      summary: WooCommerce Retrieve a Coupon
      description: Returns a single coupon by its numeric ID.
      tags:
      - Coupons
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Coupon details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
              examples:
                getCoupon200Example:
                  summary: Default getCoupon 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    code: string-value
                    amount: string-value
                    discount_type: percent
                    description: A sample description
                    date_expires: '2026-05-03T14:30:00Z'
                    usage_count: 1
                    individual_use: true
                    product_ids:
                    - 1
                    excluded_product_ids:
                    - 1
                    usage_limit: 1
                    usage_limit_per_user: 1
                    minimum_amount: string-value
                    maximum_amount: string-value
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateCoupon
      summary: WooCommerce Update a Coupon
      description: Updates an existing coupon by its numeric ID. Only provided fields are changed.
      tags:
      - Coupons
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponInput'
      responses:
        '200':
          description: Coupon updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
              examples:
                updateCoupon200Example:
                  summary: Default updateCoupon 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    code: string-value
                    amount: string-value
                    discount_type: percent
                    description: A sample description
                    date_expires: '2026-05-03T14:30:00Z'
                    usage_count: 1
                    individual_use: true
                    product_ids:
                    - 1
                    excluded_product_ids:
                    - 1
                    usage_limit: 1
                    usage_limit_per_user: 1
                    minimum_amount: string-value
                    maximum_amount: string-value
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    meta_data:
                    - string-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteCoupon
      summary: WooCommerce Delete a Coupon
      description: Deletes a coupon by its numeric ID. Set force to true to permanently delete.
      tags:
      - Coupons
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/force'
      responses:
        '200':
          description: Coupon deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
              examples:
                deleteCoupon200Example:
                  summary: Default deleteCoupon 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    code: string-value
                    amount: string-value
                    discount_type: percent
                    description: A sample description
                    date_expires: '2026-05-03T14:30:00Z'
                    usage_count: 1
                    individual_use: true
                    product_ids:
                    - 1
                    excluded_product_ids:
                    - 1
                    usage_limit: 1
                    usage_limit_per_user: 1
                    minimum_amount: string-value
                    maximum_amount: string-value
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    search:
      name: search
      in: query
      description: Limit results to those matching a string.
      required: false
      schema:
        type: string
    force:
      name: force
      in: query
      description: Set to true to permanently delete the resource, bypassing the trash.
      required: false
      schema:
        type: boolean
        default: false
    page:
      name: page
      in: query
      description: Current page of the collection. Defaults to 1.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    id:
      name: id
      in: path
      description: Unique identifier for the resource.
      required: true
      schema:
        type: integer
    after:
      name: after
      in: query
      description: Limit response to resources created after a given ISO8601 compliant date.
      required: false
      schema:
        type: string
        format: date-time
    per_page:
      name: per_page
      in: query
      description: Maximum number of items per page. Defaults to 10, maximum 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    before:
      name: before
      in: query
      description: Limit response to resources created before a given ISO8601 compliant date.
      required: false
      schema:
        type: string
        format: date-time
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: string-value
        message:
          type: string
          description: Human-readable error message.
          example: string-value
        data:
          type: object
          description: Additional error context including HTTP status code.
          properties:
            status:
              type: integer
              description: HTTP status code associated with the error.
          example:
            status: 1
    CouponInput:
      type: object
      description: Input for creating or updating a coupon.
      properties:
        code:
          type: string
          description: Coupon code (required for create).
          example: string-value
        amount:
          type: string
          description: Discount amount as a decimal string.
          example: string-value
        discount_type:
          type: string
          description: Discount type.
          enum:
          - percent
          - fixed_cart
          - fixed_product
          example: percent
        description:
          type: string
          description: Admin description.
          example: A sample description
        date_expires:
          type: string
          format: date-time
          description: Expiry date.
          example: '2026-05-03T14:30:00Z'
        individual_use:
          type: boolean
          description: Whether usable alone.
          example: true
        product_ids:
          type: array
          description: Applicable product IDs.
          items:
            type: integer
          example:
          - 1
        excluded_product_ids:
          type: array
          description: Excluded product IDs.
          items:
            type: integer
          example:
          - 1
        usage_limit:
          type: integer
          description: Total usage limit.
          example: 1
        usage_limit_per_user:
          type: integer
          description: Per-customer usage limit.
          example: 1
        minimum_amount:
          type: string
          description: Minimum order amount.
          example: string-value
        maximum_amount:
          type: string
          description: Maximum order amount.
          example: string-value
        meta_data:
          type: array
          description: Custom metadata.
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    Coupon:
      type: object
      description: A WooCommerce discount coupon.
      properties:
        id:
          type: integer
          description: Coupon unique identifier.
          example: 1
        code:
          type: string
          description: Coupon code used at checkout.
          example: string-value
        amount:
          type: string
          description: The amount of discount as a decimal string.
          example: string-value
        discount_type:
          type: string
          description: 'Determines the type of discount. Options: percent, fixed_cart, fixed_product.'
          enum:
          - percent
          - fixed_cart
          - fixed_product
          example: percent
        description:
          type: string
          description: Coupon description shown in the admin.
          example: A sample description
        date_expires:
          type: string
          format: date-time
          description: Date the coupon expires, in the site timezone.
          nullable: true
          example: '2026-05-03T14:30:00Z'
        usage_count:
          type: integer
          description: Number of times the coupon has been used.
          example: 1
        individual_use:
          type: boolean
          description: Whether the coupon can only be used alone (not with other coupons).
          example: true
        product_ids:
          type: array
          description: List of product IDs the coupon applies to.
          items:
            type: integer
          example:
          - 1
        excluded_product_ids:
          type: array
          description: List of product IDs the coupon cannot be used for.
          items:
            type: integer
          example:
          - 1
        usage_limit:
          type: integer
          description: Maximum number of times the coupon can be used in total.
          nullable: true
          example: 1
        usage_limit_per_user:
          type: integer
          description: Maximum number of times per customer the coupon can be used.
          nullable: true
          example: 1
        minimum_amount:
          type: string
          description: Minimum order amount to use the coupon.
          example: string-value
        maximum_amount:
          type: string
          description: Maximum order amount to use the coupon.
          example: string-value
        date_created:
          type: string
          format: date-time
          description: Date the coupon was created.
          example: '2026-05-03T14:30:00Z'
        date_modified:
          type: string
          format: date-time
          description: Date the coupon was last modified.
          example: '2026-05-03T14:30:00Z'
        meta_data:
          type: array
          description: Custom metadata.
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    MetaData:
      type: object
      description: Custom metadata key-value entry.
      properties:
        id:
          type: integer
          description: Metadata unique identifier.
          example: 1
        key:
          type: string
          description: Metadata key.
          example: string-value
        value:
          type: string
          description: Metadata value.
          example: string-value
  responses:
    BadRequest:
      description: The request body contains invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using the WooCommerce Consumer Key as the username and Consumer Secret as the password over HTTPS. Over plain HTTP use OAuth 1.0a one-legged authentication instead.
externalDocs:
  description: WooCommerce REST API Documentation
  url: https://woocommerce.github.io/woocommerce-rest-api-docs/