Conekta Subscriptions API

openapi: 3.1.0
info:
  contact:
    email: engineering@conekta.com
    name: Engineering Conekta
    url: https://github.com/conekta/openapi/issues
  description: Conekta sdk
  license:
    name: MIT-LICENSE
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Conekta Antifraud Subscriptions API
  version: 2.2.0
servers:
- description: Conekta main server
  url: https://api.conekta.io
security:
- bearerAuth: []
tags:
- description: All subscription-related endpoints including creation, management, and events
  name: Subscriptions
paths:
  /customers/{customer_id}/subscriptions:
    get:
      description: Get a list of subscriptions for a customer
      operationId: subscriptionList
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      - description: The numbers of items to return, the maximum value is 250
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int32
          maximum: 250
          minimum: 1
          type: integer
        style: form
      - description: General order search, e.g. by mail, reference etc.
        explode: true
        in: query
        name: search
        required: false
        schema:
          type: string
        style: form
      - description: next page
        explode: true
        in: query
        name: next
        required: false
        schema:
          type: string
        style: form
      - description: previous page
        explode: true
        in: query
        name: previous
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: List Subscriptions
      tags:
      - Subscriptions
    post:
      description: Create a new subscription for a customer (keeps existing subscriptions active)
      operationId: subscriptionCreate
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription_request'
        description: requested field for subscriptions
        required: true
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '422':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The token does not exist.
                  param: payment_method.token_id
                  code: conekta.errors.parameter_validation.payment_method.token_id.nonexistent_token
                  debug_message: The token does not exist.
                log_id: 641b6d813cd9a50001515017
                object: error
                type: parameter_validation_error
              schema:
                $ref: '#/components/schemas/error'
          description: parameter validation error
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: Create Subscription
      tags:
      - Subscriptions
  /customers/{customer_id}/subscriptions/{id}:
    get:
      description: Retrieve a specific subscription
      operationId: subscriptionsGet
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Identifier of the subscription resource
        explode: false
        in: path
        name: id
        required: true
        schema:
          example: sub_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: Get Subscription
      tags:
      - Subscriptions
    put:
      description: Update a specific subscription
      operationId: subscriptionUpdate
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Identifier of the subscription resource
        explode: false
        in: path
        name: id
        required: true
        schema:
          example: sub_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updates_a_subscription'
        description: requested field for update a subscription
        required: true
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '422':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The token does not exist.
                  param: payment_method.token_id
                  code: conekta.errors.parameter_validation.payment_method.token_id.nonexistent_token
                  debug_message: The token does not exist.
                log_id: 641b6d813cd9a50001515017
                object: error
                type: parameter_validation_error
              schema:
                $ref: '#/components/schemas/error'
          description: parameter validation error
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: Update Subscription
      tags:
      - Subscriptions
  /customers/{customer_id}/subscriptions/{id}/events:
    get:
      description: Get events for a specific subscription
      operationId: subscriptionEvents
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Identifier of the subscription resource
        explode: false
        in: path
        name: id
        required: true
        schema:
          example: sub_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      - description: The numbers of items to return, the maximum value is 250
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int32
          maximum: 250
          minimum: 1
          type: integer
        style: form
      - description: General order search, e.g. by mail, reference etc.
        explode: true
        in: query
        name: search
        required: false
        schema:
          type: string
        style: form
      - description: next page
        explode: true
        in: query
        name: next
        required: false
        schema:
          type: string
        style: form
      - description: previous page
        explode: true
        in: query
        name: previous
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_events_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: Get Subscription Events
      tags:
      - Subscriptions
  /customers/{customer_id}/subscriptions/{id}/cancel:
    post:
      description: Cancel a specific subscription
      operationId: subscriptionCancel
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Identifier of the subscription resource
        explode: false
        in: path
        name: id
        required: true
        schema:
          example: sub_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/response
            value: en
        explode: false
        in: header
        name: Accept-Language
        required: false
        schema:
          default: es
          enum:
          - es
          - en
          type: string
        style: simple
      - description: In the case of a holding company, the company id of the child company to which will process the request.
        example: 6441b6376b60c3a638da80af
        explode: false
        in: header
        name: X-Child-Company-Id
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/vnd.conekta-v2.2.0+json:
              schema:
                $ref: '#/components/schemas/subscription_response'
          description: successful
          headers:
            Date:
              description: The date and time that the response was sent
              explode: false
              schema:
                example: Fri, 03 Feb 2023 16:57:48 GMT
                type: string
              style: simple
            Content-Type:
              description: The format of the response body
              explode: false
              schema:
                example: application/json; charset=utf-8
                type: string
              style: simple
            Content-Length:
              description: The length of the response body in bytes
              explode: false
              schema:
                example: '2737'
                type: string
              style: simple
            Connection:
              description: The type of connection used to transfer the response
              explode: false
              schema:
                example: keep-alive
                type: string
              style: simple
            Conekta-Media-Type:
              explode: false
              schema:
                example: conekta-v2.2.0; format=application/json
                type: string
              style: simple
        '401':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: Please include your access key in your request.
                  code: conekta.errors.authentication.missing_key
                log_id: 507f1f77bcf86cd799439011
                object: error
                type: authentication_error
              schema:
                $ref: '#/components/schemas/error'
          description: authentication error
        '404':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - message: The resource was not found.
                  code: conekta.errors.resource_not_found.entity
                  debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could not be found.
                log_id: 641b6c253cd9a50001514fae
                object: error
                type: resource_not_found_error
              schema:
                $ref: '#/components/schemas/error'
          description: not found entity
        '500':
          content:
            application/vnd.conekta-v2.2.0+json:
              example:
                details:
                - debug_message: There was a runtime error and Conekta engineers have been notified.
                  message: There was a runtime error and Conekta engineers have been notified.
                  code: conekta.errors.api.system.general_failure
                object: error
                type: api_error
                log_id: 641b6f2b3cd9a50001515098
              schema:
                $ref: '#/components/schemas/error'
          description: internal server error
      security:
      - bearerAuth: []
      summary: Cancel Subscription
      tags:
      - Subscriptions
  /customers/{customer_id}/subscriptions/{id}/pause:
    post:
      description: Pause a specific subscription
      operationId: subscriptionPause
      parameters:
      - description: Identifier of the customer resource
        explode: false
        in: path
        name: customer_id
        required: true
        schema:
          example: cus_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Identifier of the subscription resource
        explode: false
        in: path
        name: id
        required: true
        schema:
          example: sub_2tGzG1GxtDAZHEGPH
          type: string
        style: simple
      - description: Use for knowing which language to use
        examples:
          es:
            summary: for spanish request/response
            value: es
          en:
            summary: for english request/r

# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/conekta/refs/heads/main/openapi/conekta-subscriptions-api-openapi.yml