The Subscription Promotions API from Smokeball — 3 operation(s) for subscription promotions.
openapi: 3.0.1
info:
title: Smokeball Activity Codes Subscription Promotions API
version: '1.0'
description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
contact:
name: Smokeball Developer Support
url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
x-api-id: smokeball
x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
token: []
tags:
- name: Subscription Promotions
paths:
/subscriptions/promotions:
get:
tags:
- Subscription Promotions
summary: Get all promotions
description: Returns all available promotions with their eligibility criteria and benefits.
operationId: GetPromotions
parameters:
- name: Offset
in: query
schema:
maximum: 2147483647
minimum: 0
type: integer
format: int32
- name: Limit
in: query
schema:
maximum: 500
minimum: 1
type: integer
format: int32
responses:
'200':
description: When request is successful. Returns a paged collection of 'SubscriptionPromotion' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPromotionPagedCollection'
'500':
description: When an error occurs while retrieving promotions.
x-excluded: true
/subscriptions/promotions/{id}:
get:
tags:
- Subscription Promotions
summary: Get promotion
description: Retrieves detailed information for a specific promotion.
operationId: GetPromotion
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: When request is successful. Returns a 'SubscriptionPromotion' object.
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionPromotion'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while retrieving promotion.
x-excluded: true
/subscriptions/{subscriptionId}/promotions/{id}:
post:
tags:
- Subscription Promotions
summary: Apply promotion to subscription
description: "Applies a promotion to a subscription.\r\n\r\nImportant considerations:\r\n* Some promotions may have redemption limits per subscription\r\n* Some promotions may have duration limits\r\n* Signup promotions cannot be applied to an existing subscription\r\n* Trial promotions are tied to a single tier or add-on"
operationId: ApplyPromotionAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
- name: id
in: path
description: The identifier of the promotion to apply
required: true
schema:
type: string
format: uuid
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription or promotion with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while applying promotion.
x-excluded: true
delete:
tags:
- Subscription Promotions
summary: Remove promotion from subscription
description: Removes a promotion from a subscription.
operationId: RemovePromotionAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
- name: id
in: path
description: The identifier of the promotion to remove
required: true
schema:
type: string
format: uuid
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription or promotion with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while removing promotion.
x-excluded: true
components:
schemas:
Price:
type: object
properties:
id:
type: string
description: The internal price id.
nullable: true
externalPriceId:
type: string
description: The external price id.
nullable: true
default:
type: boolean
description: Returns `true` if the price is the default price.
example: true
active:
type: boolean
description: Returns `true` if the Price is active.
example: true
type:
type: string
description: The type of price.
example: Recurring
name:
type: string
description: The price display name.
nullable: true
example: '"$109 per user/month"'
amount:
type: number
description: The per user amount for this pricing option for the specified interval (in cents).
format: double
nullable: true
example: 5900
interval:
type: string
description: Recurring payment interval type.
example: Monthly
additionalProperties: false
PromotionCode:
type: object
properties:
id:
type: string
description: Unique identifier of the promotion code.
nullable: true
example: promo_code_1234
name:
type: string
description: Display name of the promotion code.
nullable: true
example: SUMMER2024
description:
type: string
description: The description of the promotion code.
nullable: true
example: 100% discount!
code:
type: string
description: The actual code that customers can use.
nullable: true
example: SUMMER2024
active:
type: boolean
description: Whether this promotion code is currently active.
minimumAmount:
type: integer
description: Minimum amount in cents required to apply this promotion code.
format: int64
nullable: true
example: 5000
firstTimeCustomersOnly:
type: boolean
description: Whether this code can only be used by first-time customers.
limit:
type: integer
description: "Maximum number of times this code can be used.\r\nNull means unlimited uses."
format: int64
nullable: true
example: 100
createdDate:
type: string
description: When the promotion code was created.
format: date-time
example: '2024-01-15T10:00:00Z'
expiratonDate:
type: string
description: "When the promotion code expires.\r\nNull if the code does not expire."
format: date-time
nullable: true
example: '2024-12-31T23:59:59Z'
metadata:
type: object
additionalProperties:
type: string
description: Additional metadata associated with the promotion code.
nullable: true
additionalProperties: false
AddOn:
type: object
properties:
id:
type: string
description: Unique identifier of the add-on.
format: uuid
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
smokeballId:
type: string
description: "Unique Smokeball identifier of the add-on. \r\n\r\nThis identifier convenience purposes only and should not be used to interact with the subscriptions API."
nullable: true
productSuite:
type: string
description: The product suite that this add-on belongs to.
nullable: true
name:
type: string
description: The display name of the add-on.
nullable: true
example: Intake
description:
type: string
description: "The description of the add-on.\r\n\r\nCan be used to describe the add-on to a customer."
nullable: true
trialPeriodDays:
type: integer
description: "The number of days the add-on can be trialed for.\r\n\r\nCannot be trialed if zero or missing."
format: int32
nullable: true
prices:
type: array
items:
$ref: '#/components/schemas/Price'
description: The price options for the add-on.
nullable: true
createdDate:
type: string
description: The created date of the add-on.
format: date-time
example: '2022-04-23T14:00:00Z'
updatedDate:
type: string
description: The updated date of the add-on.
format: date-time
example: '2022-04-23T14:00:00Z'
additionalProperties: false
Link:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
additionalProperties: false
SubscriptionPromotion:
type: object
properties:
id:
type: string
description: Unique identifier of the promotion.
format: uuid
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
productSuite:
type: string
description: The product suite that this promotion belongs to.
nullable: true
tiers:
type: array
items:
$ref: '#/components/schemas/Tier'
description: "List of tiers this promotion can be applied to.\r\nIf tiers and add-ons are both empty, the promotion can be applied to any tier or add-on."
nullable: true
addOns:
type: array
items:
$ref: '#/components/schemas/AddOn'
description: "List of add-ons this promotion can be applied to.\r\nIf tiers and add-ons are both empty, the promotion can be applied to any tier or add-on."
nullable: true
usage:
type: array
items:
type: string
description: "The usage context of a promotion.\r\n\r\nThe context can be used by apps to determine how and when to apply a promotion."
description: "Intended usage type for this promotion.\r\n\r\n* Manual - Promotion can be applied manually at any time (with a code).\r\n\r\n* Trial - The promotion can be used for trialing tiers or add-ons.\r\n\r\n* CancelRetention - The promotion can be used when the user is trying to cancel their subscription.\r\n\r\n* DowngradeRetention - The promotion can be used when the user is trying to downgrade their subscription.\r\n\r\n* Signup - The promotion can be used on sign up."
nullable: true
name:
type: string
description: Display name of the promotion.
nullable: true
example: Summer Sale 2024
description:
type: string
description: Description of the promotion.
nullable: true
example: Summer Sale 2024
durationDays:
type: integer
description: "Number of days the promotion applies for.\r\n\r\nFor example, if the promotion is a trial promotion, how many days the associated tier or add-on will be trialed for."
format: int64
nullable: true
example: 7
amountOff:
type: integer
description: "Fixed amount off (in cents).\r\nOnly one of AmountOff or PercentOff will be set."
format: int64
nullable: true
example: 2000
percentOff:
type: number
description: "Percentage discount.\r\nOnly one of AmountOff or PercentOff will be set."
format: double
nullable: true
example: 20.5
active:
type: boolean
description: Whether the promotion is currently valid and can be applied.
numUsed:
type: integer
description: Number of times this promotion has been used.
format: int64
example: 42
createdDate:
type: string
description: When the promotion was created.
format: date-time
example: '2024-01-15T10:00:00Z'
expirationDate:
type: string
description: "When the promotion expires.\r\nNull if the promotion does not expire."
format: date-time
nullable: true
example: '2024-12-31T23:59:59Z'
codes:
type: array
items:
$ref: '#/components/schemas/PromotionCode'
description: List of promotion codes associated with this promotion.
nullable: true
metadata:
type: object
additionalProperties:
type: string
description: Additional metadata associated with the promotion code.
nullable: true
isPersistent:
type: boolean
description: "Whether the promotion persists across tier switches.\r\n\r\nFor example, if a BILL only promotion is applied to the subscription and the firm upgrades to BOOST, the Promotion should be deactivated.\r\n\r\n* If the promotion is non-persistent, it should be removed completely.\r\n\r\n* If the promotion is persistent and the firm reverts back to BILL at a later date, the promotion should automatically be reactivated."
isFree:
type: boolean
description: Whether this promotion makes the targeted tier or add-on free.
deleted:
type: boolean
description: Whether this promotion has been deleted.
nullable: true
additionalProperties: false
SubscriptionPromotionPagedCollection:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
value:
type: array
items:
$ref: '#/components/schemas/SubscriptionPromotion'
nullable: true
offset:
type: integer
format: int32
nullable: true
limit:
type: integer
format: int32
nullable: true
size:
type: integer
format: int64
first:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
previous:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
next:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
last:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
additionalProperties: false
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
Tier:
type: object
properties:
id:
type: string
description: Unique identifier of the tier.
format: uuid
example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
smokeballId:
type: string
description: "Unique Smokeball identifier of the tier. \r\n\r\nThis identifier convenience purposes only and should not be used to interact with the subscriptions API."
nullable: true
productSuite:
type: string
description: The product suite that this tier belongs to.
nullable: true
name:
type: string
description: The display name of the tier.
nullable: true
example: Intake
description:
type: string
description: "The description of the tier.\r\n\r\nCan be used to describe the tier to a customer."
nullable: true
trialPeriodDays:
type: integer
description: "The number of days the tier can be trialed for.\r\n\r\nCannot be trialed if zero or missing."
format: int32
nullable: true
prices:
type: array
items:
$ref: '#/components/schemas/Price'
description: The price options for the tier.
nullable: true
createdDate:
type: string
description: The created date of the tier.
format: date-time
example: '2022-04-23T14:00:00Z'
updatedDate:
type: string
description: The updated date of the tier.
format: date-time
example: '2022-04-23T14:00:00Z'
additionalProperties: false
securitySchemes:
api-key:
type: apiKey
name: x-api-key
in: header
token:
type: apiKey
name: Authorization
in: header
x-amazon-apigateway-authtype: cognito_user_pools