> ## Documentation Index > Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an Existing Rate Plan > Update an existing RatePlan. Note:- Once a Rate Plan is in use (assigned to at least one Subscription Item with at least one usage Event recorded) most parameters may not be redefined. Pricing and descriptions can always be updated, and will take affect on the next billing of Items using this plan, with the exception of pre-notification guarantees which will be honored for the next billing before changing the price. ## OpenAPI ````yaml /portal/SubscribeAPI.yaml post /rate_plans/{rate_plan} openapi: 3.0.0 info: title: Subscribe API description: > # Overview The REST API for Subscribe provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients # Subscribe OpenAPI YAML Reference See the [Subscribe OpenAPIs](https://docs.vindicia.com/bundle/SubscribeAPI/page/index.html) YAML file located in the [Developer Hub](https://docs.vindicia.com/category/developerhub) section of the Knowledge Center. # Environment Subscribe provides two distinct environments for testing and production: ## The Staging Environment The Staging environment allows you to test your application against the code currently running in **Production:** **https://api.staging.us-west.vindicia.com** ## The Production Environment The **Production** environment is for real-world use for actual billing and subscription activity. **https://api.vindicia.com** *Note: The examples in this API reference use the Production URL. Replace with the Staging URL, as needed.* # Interacting with the API ## Making Requests As per RESTful design patterns, the Subscribe API implements the following HTTP verbs: | Verb | Description | | ------------ | --------------------------------------------------------------------------| | GET | Retrieve resources (as a list or single record fetch) | | POST | Create new resources or update existing ones (overloading during create/update is permitted where specified) | | DELETE | Remove an ownership or hierarchical association between certain resources | Requests and Responses are made in JSON. When making requests, set the Content-Type header to **application/json**. Vindicia supports gzip compression. To receive the response body compressed in gzip format, send **content-encoding:gzip** in your request header. ## Example ``` POST /transactions Content-Type: application/json Content-Length: 94 { "object" : "Transaction", "id" : "tx_1234", "created" : "2020-01-01T00:55:47Z" } ``` ## Status Codes Subscribe uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the **2xx** range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.), and codes in the **5xx** range indicate an error with Vindicia’s servers (these are rare). When an error occurs additional information will be returned in the [error response](https://docs.vindicia.com/bundle/b_Subscribe_REST_API_Guide/page/topics/Errors.html). | Code |Status | Description | |---------|-----------------------|---------------------------------------------------------------------------| | 200 | Ok | Everything worked as expected. | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Authorization | Couldn’t authenticate your request | | 402 | Authorization Failure | Authorization failed | | 403 | Forbidden | Authentication failed - check your username and password | | 404 | Not Found | The requested resource doesn’t exist | | 429 | Too Many Requests | Too many requests hit the API too quickly. | | 500 | Internal Server Error | | | 503 | Forbidden | Authentication failed - check your username and password | ## Example Basic HTTP Response ``` HTTP/1.1 200 OK Content-Type: application/json Content-Length: 150 Request-Id: d837becba3325b62adddb2b0f1d7ab48824ff248 Connection: close { "object" : "Transaction", "id" : "tx_1234", "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e", "created" : "2020-01-01T00:55:47Z" } ``` ## Fields All resources are represented by a unique, Vindicia identifier - a vid. Many resources also provide an id field for you to record your unique identifier which can contain any alphanumeric character but must not contain a /. When referring to a resource either the vid or the id may be used. `GET https://api.vindicia.com/transactions/:id` `GET https://api.vindicia.com/transactions/:vid` Resources also have an object field which represents the resource type. #### Example Call ``` { "object" : "Transaction", "id" : "tx_1234", "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e", "created" : "2020-01-01T00:55:47Z", "url" : "/transactions/tx_1234" } ``` #### Timestamps All timestamps are represented in ISO8601 format. Timestamps may be submitted in any timezone but will be returned in UTC Time standard. #### Strings All strings are 1,024 characters unless otherwise noted. Submitting values in excess of this limit will return an error. #### Enumerable Values Some fields like **object** have a constant set of values. Submitting any value other than those documented will result in an error being returned with a status code of **400**. #### Arrays and Lists The API returns multiple resources as list objects containing JSON array. Lists provide the ability to sparsely represent the resources they contain. Additional data can be accessed through [pagination](https://docs.vindicia.com/bundle/b_Subscribe_REST_API_Guide/page/topics/Pagination.html). #### Example Request (Excerpt) ``` { "object" : "Subscription", "id" : "sub_1234", "items": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "product": { "object": "Product", "id": "prod_1234" } }, { "object": "SubscriptionItem", "id": "sub_1234.2", "product": { "object": "Product", "id": "prod_1235" } } ] ... } ``` #### Example Response (Excerpt) ``` { "items": { "object": "List", "data": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" }, { "object": "SubscriptionItem", "id": "sub_1234.2", "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" } ], "total_count": 2 } ``` ## Creating and Updating Objects For expedience and convenience most create calls for a certain object allow for the creation of sub-objects when doing the initial creation. However, updating is purposefully always an atomic operation relating to only one object to prevent accidental data loss. For example: When creating an Account you can concurrently create a new Payment Method. When updating, you will need to separately update a Payment Method by using the Payment Methods endpoints. # Authentication Authentication to the API is performed via HTTP Basic Auth using your environment specific API user and key as the username and password. *Note: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.* Example cURL Api Key Usage ```curl "https://api.vindicia.com/subscriptions" -u acaff38d462f9430d5cbcbaf:a575771fc679b9de``` Example JavaScript Api Key Usage ```constsubscribe_api_key="acaff38d462f9430d5cbcbaf:a575771fc679b9de";``` # Pagination All **GET** endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API will assign the next call into next attribute together with all the currently used pagination parameters. You know that you have paginated all the results when the return is empty (**next** value will be undefined, as well). Using cursor-based pagination protects against the situation when the resulting object list changes during pagination (new resource gets added or removed). The default limit is set to 20 but values up to 100 are permitted.
 Parameter    test    Description 
 limit   optional   A limit on the number of objects to be returned, between 1 and 100. 
 starting_after   optional   A cursor for use in pagination. starting_after is an object id that
defines your place in the list. For instance, if you make a list request and receive 100 objects,
ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. 
 ending_before   optional   A cursor for use in pagination. ending_before is an object id that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. 
Example Call ``` GET /foos Content-Type: application/json Content-Length: 32509 ``` Example Collection Pagination ``` { "object": "List", "data": [...], "total_count": 31, "url": "/foos", "next": "/foos?starting_after=Montly+Stream", "previous": "/foos?ending_before=Daily+Stream" } ``` # Errors All error responses will return an error object. ## Attributes
 Name   Type   Description 
 object   string   Value is “Error”. 
 message   string   A human-readable message providing more detailed information about the error. 
## Example Error JSON ``` { "object" : "Error", "message" : "Not implemented yet." } ``` # Versioning The API version is based on the date of the last breaking change. The current version is 20190501. To set the API version on a specific request send an **X-API-Version** header on your first call. The system will default according to your first call. Most additions to the API will not require a new version of the API. If no version is specified in the X-API Version header, the default API version will be used. # Request Ids Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution. # Endpoints The Subscribe REST API exposes key resources as endpoints, which can be manipulated using standard methods. Critical sub-resources which only work in the context of their parent are defined here under their endpoint; other sub-resources, shared between other objects but not directly manipulated are documented in the Resources section. *Note: HTTP request examples in this reference use the Production path. For the Staging environment, substitute **staging.us-west.vindicia** in place of vindicia.* Subscribe provides a RESTful API to integrate recurring and one-time payments as well as other billing concepts into your business or application. The API provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific object contact: email: support@vindicia.com license: name: Vindicia url: https://www.vindicia.com/ version: '2024.09' servers: - url: https://virtserver.swaggerhub.com/Amdocs_Media/Subscribe_API_WIP/2024.09 description: Subscribe OpenAPI specification - url: https://api.staging.us-west.vindicia.com description: Subscribe Staging for Testing - url: https://api.vindicia.com description: Subscribe Production security: - basicAuth: [] tags: - name: Accounts description: >- The Account represents a merchant’s customer. As such it can contain as much or as little information as you collect about the customers (people or organizations) to which you offer billing and subscriptions. Subscriptions and Transactions must belong to an Account - as such, Accounts will be required in Subscribe for billing. Read More in our User Guide An Account can have any number of children accounts and may have up to one parent account. Read more in our User Guide. An Account owns the “on file” payment methods to be used by it in billing - name: Activities description: >- The Activity object enables you to record activities (events) on your site that are not direct purchase transactions, such as when customers access for-pay content like song downloads. That information can serve as evidence for chargeback disputes should they occur. You make calls available for the Activity object to submit the activity data once per event. Alternatively, queue and submit the data periodically in a batch process. Usually, you collect events of interest only. For example, you need not record every page view by a customer, only those page views that contain for-pay content that the customer accessed or downloaded. - name: Address description: '' - name: Billing Plans description: >- A Billing Plan represents a pre-defined billing and pricing schedule. Every subscription is billed according to its assigned Billing Plan. A Billing Plan can be a complex object made up of one or more Billing Periods, each of which have configurable rules for how many cycles they repeat, as well as other billing, entitlement, and communication rules. The API allows you to create or update Billing Plans. You can retrieve individual plans as well as a list of all Billing Plans. - name: Campaigns description: >- Subscribe Campaigns are discounts, such as special offers or limited-time pricing, you can apply to your Products or Billing Plans. Discounts can be currency-based or percentage-based, and applied to one-time purchases or applied to a recurring subscription for a specific period. - name: Campaign Codes description: >- Subscribe Campaigns are discounts, such as special offers or limited-time pricing, you can apply to your Products or Billing Plans and are handled by the Campaigns object. Campaign Codes are the codes provided to customers that are used to redeem the campaign. - name: Cancel Fee Policy description: Cancel Fee Policy - name: Cancel Reasons description: Merchant specified reason for cancelling a subscription. - name: Chargebacks description: >- A chargeback is initiated by a customer to reverse a specific transaction charge on their billing statement. - name: Charges description: >- This model is a REST-level representation of TransactionBillingItem with type of NonRecurringCharge. Note that Charge represents only positive TBIs. An as yet unbuilt model Adjustment will represent negative TBIs. - name: Currency Amount description: >- The CurrencyAmount object represents the currency credit detail associated with a particular grant of currency credits. - name: Diagnostics description: '' - name: Discount Tickets description: >- Discount Tickets is a list of campaign codes to be applied to a Subscription/Subscription Billing Plan/Subscription Item/Charge. They provide the discounts as defined in the Campaigns. They allow you to offer multiple campaign discounts simultaneously as an array to Subscriptions or Transactions and to manage the application of these discounts. - name: Entitlements description: >- The entitlement object represents the services to which a customer is entitled. Entitlement can reside at the Account (granted directly to the Customer) or the Subscription level (granted due to purchase or presence of an active subscription). - name: Events description: >- The Event object represents a specific measured/reported usage record. You can create, retrieve, list, and edit (update) individual usage event records using the Event object. - name: Event Summary description: >- This model is a REST-level representation of Event summary of next billing item. - name: GDPR Erase description: >- Removes personal information from an account (merchant_customer) for GDPR compliance. You must provide merchant_customer_id, It should be valid and should return only a single customer account for the merchant. - name: Gift Cards description: >- Gift cards are prepaid cards used to purchase products. The Gift card holds an amount of money and currency that can be redeemed to Subscribe. The gift card object holds the information of the card itself but does not allow to redeem it, instead use Gift Card Redemptions. - name: Gift Card Redemptions description: >- Gift cards are prepaid cards used to purchase products. The Gift card holds an amount of money and currency that can be redeemed to Subscribe. The redeemed amount of the gift card is credited to the Account as a credit balance and can then serve as payment balance for existing or new subscriptions.The gift card therefore does not serve as a payment method rather a crediting mechanism of the customer's account. - name: Invoices description: >- An Invoice presents the details for a particular billing - including the charges, taxes, credits, and payments related for a particular one-time purchase or subscription billing period. The API allows you to retrieve individual Invoices as well as a list of all of your Invoices using defined filters and/or pagination. - name: Payments description: >- The Payment object is a record of a payment made against an outstanding balance. This object can be used to accept Merchant Accepted Payment methods such as cash or check or to record payments made with other active payment methods such as Paypal or credit cards. For a recorded payment, a corresponding transaction is generated and processed through the auth/capture cycle appropriate to the payment method. - name: Payment Methods description: >- The PaymentMethod object represents an on-file payment instrument, for example, credit card, PayPal, ECP, direct debit. The API allows you to create, fetch, and update Payment Methods. You can retrieve individual PaymentMethods, as well as a list of all. - name: Products description: >- The Product object represents a unique merchant product, with its own pricing, description and entitlement assignments. The API allows you to create, fetch, and update products. You can retrieve individual Product objects, as well as a list of all - name: Rate Plans description: >- Rate Plans represents a pre-defined rating schedule--tier-based pricing for rated products (usage). Both pre-paid (License-based) and post-paid (metered, that is, usage-based) services use pre-defined tiers to rate recorded events. Rate Plans support flat and per-unit pricing, volume discounts, standard consumption-based prices, included units with overage, and maximum/minimum charge limits. - name: Refunds description: >- The Refund object provides a way to reverse a charge, refunding money to the customer. You can create, and retrieve individual Refunds; as well as list all existing Refunds. Refunds require a transaction – a refund can only be executed against an existing, successfully captured transaction. Refunds can be issued for any valid amount (in the currency of the original transaction) up to the as-yet un-refunded balance of the original transaction. You can issue any number of refunds on a given transaction (until it has been fully refunded). - name: Season Sets description: >- A SeasonSet object allows you to create groups of time intervals, which may be used with Billing Plans to define both Billing Cycles, and Entitlement grants. Note :- Season Sets are best described using the Subscribe user interface, rather than the API. - name: Reason Code description: Reason codes by type. - name: Subscription description: >- Subscriptions allow you to bill an Account over time and/or on a recurring basis. A subscription ties an Account to a particular billing plan and set of purchased products (subscription items) you’ve created. The API allows you to create, update and amend/modify your subscriptions. You can retrieve individual Subscriptions as well as a list of all your Subscriptions. - name: Transactions description: >- The Transaction object provides a way to charge a customer. You can create one-time transactions, retrieve individual transactions, fetch individual transactions, and list all Transactions for a given account or subscription. Posting with a new Transaction creates a new one-time Transaction object. If “to_be_captured” is false, the request will trigger an authorization attempt (based on the provided payment method’s authorization process). If successfully authorized, a subsequent post to the transaction’s actions/capture endpoint will capture the authorized transaction. If you post a new transaction with “to_be_captured” true, it will authorize and immediately capture the transaction if successful. To refund transactions, use the refunds endpoint. - name: Tokens description: >- The token object provides a way to offer virtual currencies or track the balance of a consumable service item. paths: /rate_plans/{rate_plan}: post: tags: - Rate Plans summary: Update an Existing Rate Plan description: >- Update an existing RatePlan. Note:- Once a Rate Plan is in use (assigned to at least one Subscription Item with at least one usage Event recorded) most parameters may not be redefined. Pricing and descriptions can always be updated, and will take affect on the next billing of Items using this plan, with the exception of pre-notification guarantees which will be honored for the next billing before changing the price. operationId: updateRatePlan parameters: - name: rate_plan in: path description: The **id** or the **vid** of the RatePlan to retrieve required: true schema: type: string - name: force in: query description: >- If set to true, allows updating a Rate Plan the is in use (assigned to at least one Subscription item with at lease one usage Event recorded) required: false schema: type: boolean default: false requestBody: $ref: '#/components/requestBodies/updateRatePlanRequest' responses: '200': description: JSON A full RatePlan object. content: application/json: schema: $ref: '#/components/schemas/RatePlan' example: >- { "object": "RatePlan", "id": "rateplan_1234", "vid": "4a276f4854085d7c0b5665f61ecf8988bbfe481d", "description": "Combo: Each, Usage, Flat1", "multiply_rated_units_by": "EachRespectiveTier", "rated_unit": { "object": "RatedUnit", "name_singular": "License", "name_plural": "Licenses" }, "tier": [ { "object": "RatePlanTier", "name": "Tier 1", "rate_price": [ { "object": "RatePlanPrice", "amount": 11, "currency": "USD" } ], "charge_customer": "FlatFee", "begins_at_level": 1 }, { "object": "RatePlanTier", "name": "Tier 2", "rate_price": [ { "object": "RatePlanPrice", "amount": 50, "currency": "USD" } ], "charge_customer": "FlatFee", "begins_at_level": 11 } ], "rounding_decimals": 0, "included_units": 0, "minimum_fee": [ { "object": "RatePlanPrice", "amount": 10, "currency": "USD" } ], "maximum_fee": [], "rate_plan_model": "UsageBased", "status": "Active", "has_event_recorded": false, "created": "2022-07-05T14:57:23+00:00" } '400': description: Error - 400 Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' example: '{ "object": "Error", "message": "JSON is invalid" }' '401': description: Error - 401 Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: '' '404': description: Error - 404 Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: >- { "object": "Error", "message": "This endpoint does not exist. Check our API docs." } '500': description: Internal server error components: requestBodies: updateRatePlanRequest: description: >- JSON - This request supports the same arguments as ‘create’ (a full Rate Plan object) excepting the behavior of the **id**; providing an **id** or **vid** in the URL indicates to Subscribe that this is an update, not a create – as such, **id** and **vid** cannot be updated. content: application/json: schema: $ref: '#/components/schemas/RatePlan' example: >- { "object":"RatePlan", "id":"rateplan_1234", "description":"Combo: Each, Usage, Flat1", "multiply_rated_units_by":"EachRespectiveTier", "rated_unit":{ "object":"RatedUnit", "name_singular":"License", "name_plural":"Licenses" }, "tier":[ { "object":"RatePlanTier", "name":"Tier 1", "rate_price":[ { "object":"RatePlanPrice", "amount":11, "currency":"USD" } ], "charge_customer":"FlatFee", "begins_at_level":1 }, { "object":"RatePlanTier", "name":"Tier 2", "rate_price":[ { "object":"RatePlanPrice", "amount":50, "currency":"USD" } ], "charge_customer":"FlatFee", "begins_at_level":11 } ], "rounding_decimals":0, "included_units":0, "minimum_fee":[ { "object":"RatePlanPrice", "amount":10, "currency":"USD" } ], "maximum_fee":[], "rate_plan_model":"UsageBased", "status":"Active", "has_event_recorded":true } schemas: RatePlan: type: object properties: object: type: string description: Value is "RatePlan" enum: - RatePlan id: $ref: '#/components/schemas/ID' vid: $ref: '#/components/schemas/VID' created: type: string description: The date/time the object was created. format: date-time description: type: string description: Optional description of the rated service offering. multiply_rated_units_by: type: string description: >- Tier pricing rule. EachRespective charges units “in” that tier at its price; HighestApplicable is volume pricing, charging at the peak unit level’s tier for all units. Values can be EachRespectiveTier,HighestApplicableTier. enum: - EachRespectiveTier - HighestApplicableTier rated_unit: description: Defined rating unit of measure. allOf: - $ref: '#/components/schemas/RatedUnit' tier: type: array description: Successive pricing tiers based on unit “from/to” limits items: $ref: '#/components/schemas/RatePlanTier' rounding_decimals: type: integer description: >- Number of digits for rounding; Excel’s ROUND function- 0 = nearest integer, 2 = 2 decimal places, -2 means = nearest hundred, etc. format: int32 included_units: type: integer description: >- Number of units included for free; tier 1 starts after included units have been recorded. format: date-time minimum_fee: type: array description: Minimum charge per billing period (one price per currency) items: $ref: '#/components/schemas/RatePlanPrice' maximum_fee: type: array description: Maximum charge per billing period (one price per currency) items: $ref: '#/components/schemas/RatePlanPrice' rate_plan_model: type: string description: >- Determines pre-paid (licenses or seats billed in advance) or post-paid (usage recorded throughout the period and billed at period end. Values can be LicenseBased,UsageBased enum: - LicenseBased - UsageBased status: type: string description: >- Merchants may define whether they want to declare a plan as available to offer. Values can be Active,Suspended. enum: - Active - Suspended has_event_recorded: type: boolean description: >- Read-only field that tells whether this RatePlan has had any events recorded on it or not. metadata: type: string description: >- A set of key/value pairs that you can attach to an object. Useful for storing additional information. description: >- Rate Plans represents a pre-defined rating schedule - tier-based pricing for rated products (e.g. usage). Both pre-paid (aka License-based) and post-paid (metered, aka usage-based) services use pre-defined tiers to rate recorded events. Rate Plans support flat and per-unit pricing, volume discounts, standard consumption-based prices, included units with overage, and maximum/minimum charge limits. Error: required: - code type: object properties: code: type: string message: type: string description: The object contains information about the error. ID: maxLength: 128 type: string description: >- A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged. VID: maxLength: 128 type: string description: >- A Globally Unique Identifier (GUID) for this object. This value is generated by Vindicia. RatedUnit: type: object properties: name_singular: type: string description: Singular name of units. name_plural: type: string description: Plural name of units. RatePlanTier: type: object properties: name: type: string rate_price: type: array description: >- Required. An array of RatePlanPrice objects, which define the Price (or prices) for this Tier (one price for each currency used). items: $ref: '#/components/schemas/RatePlanPrice' charge_customer: type: string description: >- Can be- FlatFee which defines a stepped pricing structure, in which the customer is charged the ratePrice per Tier or PerUnit which defines a graduated pricing structure, in which the customer is charged the number of units accessed, multiplied by the ratePrice per Tier. enum: - Flatfee - PerUnit begins_at_level: type: integer description: >- The number of Units at which this Tier’s pricing structure takes effect. The number of Units defined for each Tier runs from the minimum value of the Tier, to one Unit less than the minimum value of the next higher Tier. Typically the first tier would have beginsAtLevel = 1. The final, highest tier is unbounded (infinite). RatePlanPrice: type: object properties: amount: type: integer description: Amount currency: type: string description: ISO 4217 Currency Code. securitySchemes: basicAuth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.