@maxio-com/advanced-billing-sdk
Version:
Ultimate billing and pricing flexibility for B2B SaaS. Maxio integrates directly into your product, so you can seamlessly manage your product catalog, bill customers, and collect payments.
356 lines • 19.8 kB
TypeScript
/**
* AdvancedBilling
*
* This file was automatically generated for Maxio by APIMATIC v3.0 ( https://www.apimatic.io ).
*/
import { ApiResponse, RequestOptions } from '../core.js';
import { CouponCurrencyRequest } from '../models/couponCurrencyRequest.js';
import { CouponCurrencyResponse } from '../models/couponCurrencyResponse.js';
import { CouponRequest } from '../models/couponRequest.js';
import { CouponResponse } from '../models/couponResponse.js';
import { CouponSubcodes } from '../models/couponSubcodes.js';
import { CouponSubcodesResponse } from '../models/couponSubcodesResponse.js';
import { CouponUsage } from '../models/couponUsage.js';
import { ListCouponsFilter } from '../models/listCouponsFilter.js';
import { BaseController } from './baseController.js';
export declare class CouponsController extends BaseController {
/**
* ## Coupons Documentation
*
* Coupons can be administered in the Advanced Billing application or created via API. View our section
* on [creating coupons](https://maxio.zendesk.com/hc/en-us/articles/24261212433165-Creating-Editing-
* Deleting-Coupons) for more information.
*
* Additionally, for documentation on how to apply a coupon to a subscription within the Advanced
* Billing UI, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-
* Coupons-and-Subscriptions).
*
* ## Create Coupon
*
* This request will create a coupon, based on the provided information.
*
* You can create either a flat amount coupon, by specyfing `amount_in_cents`, or percentage coupon by
* specyfing `percentage`.
*
* You can restrict a coupon to only apply to specific products / components by optionally passing in
* `restricted_products` and/or `restricted_components` objects in the format:
* `{ "<product_id/component_id>": boolean_value }`
*
* @param productFamilyId The Advanced Billing id of the product family to which the
* coupon belongs
* @param body
* @return Response from the API call
*/
createCoupon(productFamilyId: number, body?: CouponRequest, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* List coupons for a specific Product Family in a Site.
*
* @param productFamilyId The Advanced Billing id of the product family to which the
* coupon belongs
* @param page Result records are organized in pages. By default, the first
* page of results is displayed. The page parameter specifies a
* page number of results to fetch. You can start navigating
* through the pages to consume the results. You do this by
* passing in a page parameter. Retrieve the next page by adding
* ?page=2 to the query string. If there are no results to
* return, then an empty result set will be returned. Use in
* query `page=1`.
* @param perPage This parameter indicates how many records to fetch in each
* request. Default value is 30. The maximum allowed values is
* 200; any per_page value over 200 will be changed to 200. Use
* in query `per_page=200`.
* @param filter Filter to use for List Coupons operations
* @param currencyPrices When fetching coupons, if you have defined multiple
* currencies at the site level, you can optionally pass the `?
* currency_prices=true` query param to include an array of
* currency price data in the response. Use in query
* `currency_prices=true`.
* @return Response from the API call
*/
listCouponsForProductFamily({ productFamilyId, page, perPage, filter, currencyPrices, }: {
productFamilyId: number;
page?: number;
perPage?: number;
filter?: ListCouponsFilter;
currencyPrices?: boolean;
}, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse[]>>;
/**
* You can search for a coupon via the API with the find method. By passing a code parameter, the find
* will attempt to locate a coupon that matches that code. If no coupon is found, a 404 is returned.
*
* If you have more than one product family and if the coupon you are trying to find does not belong to
* the default product family in your site, then you will need to specify (either in the url or as a
* query string param) the product family id.
*
* @param productFamilyId The Advanced Billing id of the product family to which the coupon belongs
* @param code The code of the coupon
* @param currencyPrices When fetching coupons, if you have defined multiple currencies at the site
* level, you can optionally pass the `?currency_prices=true` query param to
* include an array of currency price data in the response.
* @return Response from the API call
*/
findCoupon(productFamilyId?: number, code?: string, currencyPrices?: boolean, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* You can retrieve the Coupon via the API with the Show method. You must identify the Coupon in this
* call by the ID parameter that Advanced Billing assigns.
* If instead you would like to find a Coupon using a Coupon code, see the Coupon Find method.
*
* When fetching a coupon, if you have defined multiple currencies at the site level, you can
* optionally pass the `?currency_prices=true` query param to include an array of currency price data
* in the response.
*
* If the coupon is set to `use_site_exchange_rate: true`, it will return pricing based on the current
* exchange rate. If the flag is set to false, it will return all of the defined prices for each
* currency.
*
* @param productFamilyId The Advanced Billing id of the product family to which the coupon belongs
* @param couponId The Advanced Billing id of the coupon
* @param currencyPrices When fetching coupons, if you have defined multiple currencies at the site
* level, you can optionally pass the `?currency_prices=true` query param to
* include an array of currency price data in the response.
* @return Response from the API call
*/
readCoupon(productFamilyId: number, couponId: number, currencyPrices?: boolean, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* ## Update Coupon
*
* You can update a Coupon via the API with a PUT request to the resource endpoint.
*
* You can restrict a coupon to only apply to specific products / components by optionally passing in
* hashes of `restricted_products` and/or `restricted_components` in the format:
* `{ "<product/component_id>": boolean_value }`
*
* @param productFamilyId The Advanced Billing id of the product family to which the
* coupon belongs
* @param couponId The Advanced Billing id of the coupon
* @param body
* @return Response from the API call
*/
updateCoupon(productFamilyId: number, couponId: number, body?: CouponRequest, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* You can archive a Coupon via the API with the archive method.
* Archiving makes that Coupon unavailable for future use, but allows it to remain attached and
* functional on existing Subscriptions that are using it.
* The `archived_at` date and time will be assigned.
*
* @param productFamilyId The Advanced Billing id of the product family to which the coupon belongs
* @param couponId The Advanced Billing id of the coupon
* @return Response from the API call
*/
archiveCoupon(productFamilyId: number, couponId: number, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* You can retrieve a list of coupons.
*
* @param page Result records are organized in pages. By default, the first
* page of results is displayed. The page parameter specifies a
* page number of results to fetch. You can start navigating
* through the pages to consume the results. You do this by
* passing in a page parameter. Retrieve the next page by adding ?
* page=2 to the query string. If there are no results to return,
* then an empty result set will be returned. Use in query
* `page=1`.
* @param perPage This parameter indicates how many records to fetch in each
* request. Default value is 30. The maximum allowed values is 200;
* any per_page value over 200 will be changed to 200. Use in
* query `per_page=200`.
* @param filter Filter to use for List Coupons operations
* @param currencyPrices When fetching coupons, if you have defined multiple currencies
* at the site level, you can optionally pass the `?
* currency_prices=true` query param to include an array of
* currency price data in the response. Use in query
* `currency_prices=true`.
* @return Response from the API call
*/
listCoupons({ page, perPage, filter, currencyPrices, }: {
page?: number;
perPage?: number;
filter?: ListCouponsFilter;
currencyPrices?: boolean;
}, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse[]>>;
/**
* This request will provide details about the coupon usage as an array of data hashes, one per product.
*
* @param productFamilyId The Advanced Billing id of the product family to which the coupon belongs.
* @param couponId The Advanced Billing id of the coupon.
* @return Response from the API call
*/
readCouponUsage(productFamilyId: number, couponId: number, requestOptions?: RequestOptions): Promise<ApiResponse<CouponUsage[]>>;
/**
* You can verify if a specific coupon code is valid using the `validate` method. This method is useful
* for validating coupon codes that are entered by a customer. If the coupon is found and is valid, the
* coupon will be returned with a 200 status code.
*
* If the coupon is invalid, the status code will be 404 and the response will say why it is invalid.
* If the coupon is valid, the status code will be 200 and the coupon will be returned. The following
* reasons for invalidity are supported:
*
* + Coupon not found
* + Coupon is invalid
* + Coupon expired
*
* If you have more than one product family and if the coupon you are validating does not belong to the
* first product family in your site, then you will need to specify the product family, either in the
* url or as a query string param. This can be done by supplying the id or the handle in the `handle:my-
* family` format.
*
* Eg.
*
* ```
* https://<subdomain>.chargify.com/product_families/handle:<product_family_handle>/coupons/validate.
* <format>?code=<coupon_code>
* ```
*
* Or:
*
* ```
* https://<subdomain>.chargify.com/coupons/validate.<format>?
* code=<coupon_code>&product_family_id=<id>
* ```
*
* @param code The code of the coupon
* @param productFamilyId The Advanced Billing id of the product family to which the coupon belongs
* @return Response from the API call
*/
validateCoupon(code: string, productFamilyId?: number, requestOptions?: RequestOptions): Promise<ApiResponse<CouponResponse>>;
/**
* This endpoint allows you to create and/or update currency prices for an existing coupon. Multiple
* prices can be created or updated in a single request but each of the currencies must be defined on
* the site level already and the coupon must be an amount-based coupon, not percentage.
*
* Currency pricing for coupons must mirror the setup of the primary coupon pricing - if the primary
* coupon is percentage based, you will not be able to define pricing in non-primary currencies.
*
* @param couponId The Advanced Billing id of the coupon
* @param body
* @return Response from the API call
*/
createOrUpdateCouponCurrencyPrices(couponId: number, body?: CouponCurrencyRequest, requestOptions?: RequestOptions): Promise<ApiResponse<CouponCurrencyResponse>>;
/**
* ## Coupon Subcodes Intro
*
* Coupon Subcodes allow you to create a set of unique codes that allow you to expand the use of one
* coupon.
*
* For example:
*
* Master Coupon Code:
*
* + SPRING2020
*
* Coupon Subcodes:
*
* + SPRING90210
* + DP80302
* + SPRINGBALTIMORE
*
* Coupon subcodes can be administered in the Admin Interface or via the API.
*
* When creating a coupon subcode, you must specify a coupon to attach it to using the coupon_id. Valid
* coupon subcodes are all capital letters, contain only letters and numbers, and do not have any
* spaces. Lowercase letters will be capitalized before the subcode is created.
*
* ## Coupon Subcodes Documentation
*
* Full documentation on how to create coupon subcodes in the Advanced Billing UI can be located
* [here](https://maxio.zendesk.com/hc/en-us/articles/24261208729229-Coupon-Codes).
*
* Additionally, for documentation on how to apply a coupon to a Subscription within the Advanced
* Billing UI, see our documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24261259337101-
* Coupons-and-Subscriptions).
*
* ## Create Coupon Subcode
*
* This request allows you to create specific subcodes underneath an existing coupon code.
*
* *Note*: If you are using any of the allowed special characters ("%", "@", "+", "-", "_", and "."),
* you must encode them for use in the URL.
*
* % to %25
* @ to %40
* + to %2B
* - to %2D
* _ to %5F
* . to %2E
*
* So, if the coupon subcode is `20%OFF`, the URL to delete this coupon subcode would be: `https:
* //<subdomain>.chargify.com/coupons/567/codes/20%25OFF.<format>`
*
* @param couponId The Advanced Billing id of the coupon
* @param body
* @return Response from the API call
*/
createCouponSubcodes(couponId: number, body?: CouponSubcodes, requestOptions?: RequestOptions): Promise<ApiResponse<CouponSubcodesResponse>>;
/**
* This request allows you to request the subcodes that are attached to a coupon.
*
* @param couponId The Advanced Billing id of the coupon
* @param page Result records are organized in pages. By default, the first page of results is
* displayed. The page parameter specifies a page number of results to fetch. You can
* start navigating through the pages to consume the results. You do this by passing in a
* page parameter. Retrieve the next page by adding ?page=2 to the query string. If there
* are no results to return, then an empty result set will be returned. Use in query
* `page=1`.
* @param perPage This parameter indicates how many records to fetch in each request. Default value is
* 20. The maximum allowed values is 200; any per_page value over 200 will be changed to
* 200. Use in query `per_page=200`.
* @return Response from the API call
*/
listCouponSubcodes({ couponId, page, perPage, }: {
couponId: number;
page?: number;
perPage?: number;
}, requestOptions?: RequestOptions): Promise<ApiResponse<CouponSubcodes>>;
/**
* You can update the subcodes for the given Coupon via the API with a PUT request to the resource
* endpoint.
* Send an array of new coupon subcodes.
*
* **Note**: All current subcodes for that Coupon will be deleted first, and replaced with the list of
* subcodes sent to this endpoint.
* The response will contain:
*
* + The created subcodes,
*
* + Subcodes that were not created because they already exist,
*
* + Any subcodes not created because they are invalid.
*
* @param couponId The Advanced Billing id of the coupon
* @param body
* @return Response from the API call
*/
updateCouponSubcodes(couponId: number, body?: CouponSubcodes, requestOptions?: RequestOptions): Promise<ApiResponse<CouponSubcodesResponse>>;
/**
* ## Example
*
* Given a coupon with an ID of 567, and a coupon subcode of 20OFF, the URL to `DELETE` this coupon
* subcode would be:
*
* ```
* http://subdomain.chargify.com/coupons/567/codes/20OFF.<format>
* ```
*
* Note: If you are using any of the allowed special characters (“%”, “@”, “+”, “-”, “_”, and “.”), you
* must encode them for use in the URL.
*
* | Special character | Encoding |
* |-------------------|----------|
* | % | %25 |
* | @ | %40 |
* | + | %2B |
* | – | %2D |
* | _ | %5F |
* | . | %2E |
*
* ## Percent Encoding Example
*
* Or if the coupon subcode is 20%OFF, the URL to delete this coupon subcode would be: @https:
* //<subdomain>.chargify.com/coupons/567/codes/20%25OFF.<format>
*
* @param couponId The Advanced Billing id of the coupon to which the subcode belongs
* @param subcode The subcode of the coupon
* @return Response from the API call
*/
deleteCouponSubcode(couponId: number, subcode: string, requestOptions?: RequestOptions): Promise<ApiResponse<void>>;
}
//# sourceMappingURL=couponsController.d.ts.map