> ## Documentation Index > Fetch the complete documentation index at: https://docs.tagada.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a renewal cycle > Claims one subscription or group period (V2's billing_period_key) and collects it. A second create for the period answers cycle_exists_for_period with its cycle_id; a period V2 holds answers period_claimed_by_v2; another period of a subject whose cycle is still open answers cycle_open_for_subject. ## OpenAPI ````yaml /payments-api/openapi.json post /v1/renewal-cycles openapi: 3.1.0 info: title: TagadaPay Payments API version: '2026-11-01' servers: - url: https://api.tagada.io security: [] paths: /v1/renewal-cycles: post: tags: - renewal_cycles summary: Create a renewal cycle description: >- Claims one subscription or group period (V2's billing_period_key) and collects it. A second create for the period answers cycle_exists_for_period with its cycle_id; a period V2 holds answers period_claimed_by_v2; another period of a subject whose cycle is still open answers cycle_open_for_subject. operationId: renewalCycles.create parameters: - description: Required for platform keys; refused for secret/publishable keys. in: header name: payments-account required: false schema: description: Required for platform keys; refused for secret/publishable keys. type: string - in: header name: payments-version required: false schema: enum: - '2026-11-01' type: string - in: header name: idempotency-key required: true schema: maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRenewalCycle' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RenewalCycle' description: Renewal cycle with its tries. '400': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: >- parameter_invalid, parameter_missing, amount_out_of_range, stored_credential_missing '401': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: authentication_required '403': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: permission_denied '404': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: resource_not_found '409': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: >- idempotency_key_reused, idempotency_key_in_progress, no_active_policy, cycle_exists_for_period, cycle_open_for_subject, period_claimed_by_v2, period_left_to_v2, period_refused, store_not_on_payments_api '429': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: rate_limited '500': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: internal_error '501': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: not_implemented '503': content: application/json: schema: $ref: '#/components/schemas/RenewalCycleApiError' description: payments_api_disabled security: - bearerAuth: [] components: schemas: CreateRenewalCycle: additionalProperties: false properties: amount: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer currency: enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - UYI - UYU - UYW - UZS - VED - VES - VND - VUV - WST - XAD - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMW - ZWG type: string customer: pattern: ^cus_[a-f0-9]{12}$ type: string due_at: format: date-time type: string payment_method: pattern: ^inst_[a-f0-9]{12}$ type: string period_ref: description: V2's billing_period_key. minLength: 1 type: string store: pattern: ^store_[a-f0-9]{12}$ type: string subscription_group_id: minLength: 1 type: string subscription_id: minLength: 1 type: string test_clock: description: Test mode only. pattern: ^clk_[0-9a-hjkmnp-tv-z]{26}$ type: string required: - period_ref - customer - payment_method - amount - currency - due_at type: object RenewalCycle: properties: amount: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer card_update_until: format: date-time type: - string - 'null' concluded_at: format: date-time type: - string - 'null' created_at: format: date-time type: string currency: type: string customer: type: string due_at: format: date-time type: string ending: enum: - cancel - pause - null type: - string - 'null' id: pattern: ^rcy_[0-9a-hjkmnp-tv-z]{26}$ type: string mode: enum: - live - test type: string next_try_at: format: date-time type: - string - 'null' notice_sent_at: format: date-time type: - string - 'null' object: enum: - renewal_cycle type: string outcome_reason: type: - string - 'null' payment_method: type: string period_ref: type: string policy_version: type: - string - 'null' status: enum: - scheduled - trying - waiting_retry - waiting_card_update - waiting_customer - waiting_merchant - succeeded - failed - canceled type: string x-extensible-enum: - scheduled - trying - waiting_retry - waiting_card_update - waiting_customer - waiting_merchant - succeeded - failed - canceled store: type: string subscription_group_id: type: - string - 'null' subscription_id: type: - string - 'null' test_clock: pattern: ^clk_[0-9a-hjkmnp-tv-z]{26}$ type: - string - 'null' tries: items: properties: amount: description: Integer amount in the currency minor unit. maximum: 2147483647 minimum: 0 type: integer payment: type: string priced: type: boolean processor: type: - string - 'null' retry: minimum: 0 type: integer state: enum: - trying - paid - declined - skipped type: string switched: type: boolean required: - payment - processor - amount - retry - switched - priced - state type: object type: array required: - id - object - mode - store - customer - subscription_id - subscription_group_id - period_ref - amount - currency - payment_method - status - due_at - next_try_at - card_update_until - notice_sent_at - ending - outcome_reason - tries - policy_version - test_clock - created_at - concluded_at type: object RenewalCycleApiError: properties: error: properties: code: $ref: '#/components/schemas/RenewalCycleErrorCode' details: $ref: '#/components/schemas/RenewalCycleErrorDetails' message: type: string param: type: - string - 'null' request_id: type: string type: enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - unavailable_error type: string required: - type - code - message - param - request_id type: object required: - error type: object RenewalCycleErrorCode: enum: - amount_out_of_range - authentication_required - cycle_exists_for_period - cycle_not_open - cycle_open_for_subject - idempotency_key_in_progress - idempotency_key_reused - internal_error - no_active_policy - not_implemented - notice_not_due - parameter_invalid - parameter_missing - payment_method_not_usable - payments_api_disabled - period_claimed_by_v2 - period_left_to_v2 - period_refused - permission_denied - rate_limited - resource_not_found - store_not_on_payments_api - stored_credential_missing - try_refused_by_law type: string x-extensible-enum: - amount_out_of_range - authentication_required - cycle_exists_for_period - cycle_not_open - cycle_open_for_subject - idempotency_key_in_progress - idempotency_key_reused - internal_error - no_active_policy - not_implemented - notice_not_due - parameter_invalid - parameter_missing - payment_method_not_usable - payments_api_disabled - period_claimed_by_v2 - period_left_to_v2 - period_refused - permission_denied - rate_limited - resource_not_found - store_not_on_payments_api - stored_credential_missing - try_refused_by_law RenewalCycleErrorDetails: additionalProperties: {} properties: credential_reason: enum: - inactive_instrument - customer_mismatch - credential_revoked - no_off_session_agreement - no_network_transaction_id - no_chargeable_token - billed_by_integration - not_a_card - wallet_without_processor_token - not_routable - null type: - string - 'null' cycle_id: pattern: ^rcy_[0-9a-hjkmnp-tv-z]{26}$ type: string earliest_at: format: date-time type: - string - 'null' first_seen: description: True only for the first refused offer of this subject and period. type: boolean reason: enum: - store_not_on_payments_api - period_claimed_by_v2 - billed_by_integration - period_in_v2_dunning - credential_v2_only - inactive_instrument - customer_mismatch - credential_revoked - no_off_session_agreement - no_network_transaction_id - no_chargeable_token - not_a_card - wallet_without_processor_token - not_routable - law - minimum_wait - advice_code - card_budget - tombstone - payments_api_disabled type: string type: object securitySchemes: bearerAuth: description: >- Secret, platform or publishable API key. Platform keys require Payments-Account. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.