---
updatedAt: 2026-04-20T20:21:21.000Z
agentTools:
projectIndex: https://docs.paymentlabs.io/llms.txt
---
# Create Plan Offer
Creates a plan offer
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Payin API Specification",
"version": "0.0.1",
"description": "Describes the operations a Merchant can do to manage payins"
},
"paths": {
"/subscription/plans/offers": {
"post": {
"operationId": "Create Plan Offer Endpoint",
"tags": [
"Subscription"
],
"description": "Creates a plan offer",
"summary": "Create Plan Offer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"buyer": {
"description": "Information about the buyer",
"type": "object",
"properties": {
"referenceId": {
"description": "A cross identifiable id between systems, this should be something you can reference back on your system",
"type": "string",
"title": "referenceId"
},
"email": {
"description": "The buyer's email",
"type": "string",
"title": "email"
}
},
"required": [
"email"
],
"title": "buyer"
},
"description": {
"description": "The description of this offer",
"type": "string",
"title": "description"
},
"subscriptionPlanIds": {
"description": "The plan ids for this offer",
"type": "array",
"items": {
"type": "string"
},
"title": "subscriptionPlanIds"
},
"expiresAt": {
"description": "The day this checkout will expire, won't accept payments after this date\ndefaults to 1 year from now",
"format": "date",
"type": "string",
"title": "expiresAt"
},
"userTimezone": {
"description": "The user timezone, in IANA format (e.g.: America/Sao_Paulo)\ndefaults to UTC",
"type": "string",
"title": "userTimezone"
}
},
"required": [
"buyer",
"subscriptionPlanIds"
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanOfferDto"
}
}
}
},
"400": {
"description": "\nReturned when the request has an error, check the code and message for more information about the error\n
\n\n Validation error response, when the request has invalid data, check the details for more information on what is wrong.\n
\n \n e.g.: When creating a new record, if the user tries to create a record with a missing required field, the server can return a 400 status code with a validation error response.\n \n
",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"title": "code"
},
"message": {
"type": "string",
"title": "message"
}
},
"required": [
"code",
"message"
]
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"VALIDATION_ERROR"
],
"title": "code"
},
"message": {
"type": "string",
"title": "message"
},
"details": {
"type": "object",
"title": "details"
}
},
"required": [
"code",
"details",
"message"
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized response, when the user is not authenticated or the authentication token is missing in the header.
",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"enum": [
"Unauthorized"
],
"title": "message"
}
},
"required": [
"message"
]
}
}
}
},
"403": {
"description": "\n Forbidden response, when the user is authenticated but does not have the necessary permissions.\n
",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"title": "code"
},
"message": {
"type": "string",
"title": "message"
}
},
"required": [
"code",
"message"
]
}
}
}
}
},
"security": [
{
"bearerToken": []
}
]
}
}
},
"servers": [
{
"url": "https://api-sandbox.paymentlabs.io",
"description": "Sandbox Server"
},
{
"url": "https://api.paymentlabs.io",
"description": "Production Server"
}
],
"components": {
"securitySchemes": {
"bearerToken": {
"scheme": "bearer",
"type": "http",
"bearerFormat": "JWT",
"description": "Bearer Token using JWT"
}
},
"schemas": {
"Money": {
"description": "Represents an amount of a given currency",
"title": "Money",
"type": "object",
"properties": {
"value": {
"description": "The amount in float point value",
"type": "number",
"title": "value"
},
"currency": {
"description": "The currency in ISO format",
"type": "string",
"title": "currency"
},
"formattedValue": {
"description": "The formatted value with currency",
"type": "string",
"title": "formattedValue"
},
"digits": {
"description": "Decimal digits for the currency",
"type": "number",
"title": "digits"
},
"wholeValue": {
"description": " The value, without any float points
\n Usually how many cents, depending if the currency has cent \n
",
"type": "number",
"title": "wholeValue"
}
},
"required": [
"currency",
"digits",
"formattedValue",
"value",
"wholeValue"
]
},
"InstrumentType": {
"title": "InstrumentType",
"enum": [
"bank-transfer-2",
"bank-transfer-3",
"payment-card-1",
"payment-card-2",
"payment-card-3",
"payment-card-present-3",
"third-party-token-1",
"third-party-token-3"
],
"type": "string"
},
"AuditInfo": {
"description": "Information about changes",
"title": "AuditInfo",
"type": "object",
"properties": {
"createdBy": {
"description": "User who created this record",
"type": "string",
"title": "createdBy"
},
"updatedBy": {
"description": "User who updated this record",
"type": "string",
"title": "updatedBy"
},
"updatedAt": {
"description": "Last update date",
"format": "date-time",
"type": "string",
"title": "updatedAt"
},
"createdAt": {
"description": "Date of creation",
"format": "date-time",
"type": "string",
"title": "createdAt"
}
}
},
"Schedule": {
"title": "Schedule",
"type": "object",
"properties": {
"interval": {
"$ref": "#/components/schemas/ScheduleInterval",
"description": "A scheduled interval",
"title": "interval"
},
"intervalCount": {
"description": "How many interval counts elapsed to run this schedule
\nFor example, if interval is 'monthly' and intervalCount is 2, the schedule will run every 2 months
",
"type": "number",
"title": "intervalCount"
}
},
"required": [
"interval",
"intervalCount"
]
},
"ScheduleInterval": {
"title": "ScheduleInterval",
"enum": [
"daily",
"monthly",
"weekly",
"yearly"
],
"type": "string"
},
"SubscriptionPlanDto": {
"title": "SubscriptionPlanDto",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"description": "This plan's ID",
"type": "string",
"title": "id"
},
"merchantId": {
"description": "The merchant owner of this plan",
"type": "string",
"title": "merchantId"
},
"merchantDisplayName": {
"description": "The merchant's display name",
"type": "string",
"title": "merchantDisplayName"
},
"sort": {
"description": "Sorting information, this can be used to order and group the plans
\nFor example, you can use this to group plans by type, or to order them by price
\n\n \n - PromotionalPlan#100
\n - PromotionalPlan#200
\n - RegularPlan#100
\n - RegularPlan#200
\n
\n",
"type": "string",
"title": "sort"
},
"name": {
"description": "The plan's name",
"type": "string",
"title": "name"
},
"description": {
"description": "A brief description for the plan",
"type": "string",
"title": "description"
},
"schedule": {
"$ref": "#/components/schemas/Schedule",
"description": "The schedule this plan will be charged",
"title": "schedule"
},
"amount": {
"$ref": "#/components/schemas/Money",
"description": "The amount to be charged for the plan for each scheduled interval",
"title": "amount"
},
"trialPeriod": {
"$ref": "#/components/schemas/Schedule",
"description": "An optional trial period for this plan",
"title": "trialPeriod"
},
"enabledCheckoutInstruments": {
"description": "The enabled checkout instruments for this plan",
"type": "array",
"items": {
"$ref": "#/components/schemas/InstrumentType"
},
"title": "enabledCheckoutInstruments"
},
"auditInfo": {
"$ref": "#/components/schemas/AuditInfo",
"description": "The audit info for this plan",
"title": "auditInfo"
},
"status": {
"$ref": "#/components/schemas/SubscriptionPlanStatus",
"description": "Subscription Plan status\n\n - ACTIVE: The plan is active and the user can subscribe to ir
\n - CANCELED: The plan cannot be subscribed
\n
",
"title": "status"
}
},
"required": [
"amount",
"auditInfo",
"enabledCheckoutInstruments",
"id",
"merchantDisplayName",
"merchantId",
"name",
"schedule",
"sort",
"status"
]
},
{
"$ref": "#/components/schemas/LegalDocsEnabled"
}
]
},
"SubscriptionPlanStatus": {
"title": "SubscriptionPlanStatus",
"enum": [
"ACTIVE",
"CANCELED"
],
"type": "string"
},
"LegalDocsEnabled": {
"title": "LegalDocsEnabled",
"type": "object",
"properties": {
"termsOfServiceUrl": {
"description": "The merchant's terms of service url that will be displayed to the buyer",
"type": "string",
"title": "termsOfServiceUrl"
},
"privacyPolicyUrl": {
"description": "The merchant's privacy policy url that will be displayed to the buyer",
"type": "string",
"title": "privacyPolicyUrl"
}
}
},
"PlanOfferDto": {
"title": "PlanOfferDto",
"type": "object",
"properties": {
"id": {
"description": "The offer id",
"type": "string",
"title": "id"
},
"merchantId": {
"description": "The merchant id this offer belongs to",
"type": "string",
"title": "merchantId"
},
"userId": {
"description": "The user id this offer is for",
"type": "string",
"title": "userId"
},
"userEmail": {
"description": "The user email this offer is for",
"type": "string",
"title": "userEmail"
},
"description": {
"description": "The description of this offer",
"type": "string",
"title": "description"
},
"subscriptionPlanIds": {
"description": "The plan ids for this offer",
"type": "array",
"items": {
"type": "string"
},
"title": "subscriptionPlanIds"
},
"subscriptionPlans": {
"description": "The subscription plans for this offer",
"type": "array",
"items": {
"$ref": "#/components/schemas/SubscriptionPlanDto"
},
"title": "subscriptionPlans"
},
"expiresAt": {
"description": "The date time this offer expires",
"format": "date-time",
"type": "string",
"title": "expiresAt"
},
"auditInfo": {
"$ref": "#/components/schemas/AuditInfo",
"description": "The audit info for this offer",
"title": "auditInfo"
},
"links": {
"type": "object",
"properties": {
"embeddable": {
"description": "The iframe embeddable url to render the offer",
"type": "string",
"title": "embeddable"
},
"self": {
"description": "The clean link to send directly to the user",
"type": "string",
"title": "self"
}
},
"required": [
"embeddable",
"self"
],
"title": "links"
}
},
"required": [
"auditInfo",
"expiresAt",
"id",
"links",
"merchantId",
"subscriptionPlanIds",
"subscriptionPlans",
"userEmail",
"userId"
]
}
}
}
}
```