Working with producers
You can query for, create, and modify producers through Cloud API.
Querying for producers
- GET
/billing/v1/producers
- GET
/billing/v1/producers/{producerId}
For example, the following GET request retrieves a single producer:
GET /billing/v1/producers/bc:178
{
"data": {
"attributes": {
"advanceBalance": {
"amount": "0.00",
"currency": "usd"
},
"commissionPaidYearToDateForAllCurrencies": {
"amount": "0",
"currency": "usd"
},
"currency": {
"code": "usd",
"name": "USD"
},
"defaultPaymentInstrument": {
"displayName": "Responsive",
"id": "bc:SPTgtsE8phr-8_87hNl2A",
"type": "UniversalPaymentInstrument",
"uri": "/billing/v1/universal-payment-instruments/bc:SPTgtsE8phr-8_87hNl2A"
},
"holdStatement": true,
"id": "bc:178",
"name": "Standard Producer",
"recurDayOfMonth": 15,
"recurPeriodicity": {
"code": "quarterly",
"name": "Quarterly"
...
}
}
}
}
Producers can be associated with security zones. This may affect the producers that are returned, depending on the user that submits the request. For more information, see Security zones.
sort
query parameter when querying for producers to
sort the returned producers by producer tier:/billing/v1/producers?sort=tier
Creating producers
- POST
/billing/v1/producers
The following fields are required to create a producer:
Field | Value | Description |
currency |
Typekey reference to the Currency
typelist |
The primary currency supported by the producer. |
name |
String | The name of the producer. |
recurDayOfMonth |
Integer | The day of the month commission payments are made. |
recurPeriodicity |
Typekey reference to the Periodicity
typelist |
Specifies how often commission payments are made. This is almost always monthly. |
tier |
A reference to the ProducerTier
typelist |
The producer's tier (in the base configuration,
gold , silver , or
bronze ). This determines which commission plans
are available to the producer. |
The following is a minimal POST to create a producer.
POST /billing/v1/producers
Request body
{
"data": {
"attributes": {
"currency": {
"code": "usd"
},
"name": "Cloud API Producer",
"recurDayOfMonth": 15,
"recurPeriodicity": {
"code": "monthly"
},
"tier": {
"code": "gold"
}
}
}
}
Modifying producers
Modify a producer using the following endpoint:
- PATCH
/billing/v1/producers/{producerId}
You can patch any fields on a producer except for name
and
currency
. These two fields cannot be altered from the values set
when the producer was created.
The following example call updates a producer to have a new agency bill plan:
Command
PATCH /billing/v1/producers/bc:178
Request body
{
"data": {
"attributes": {
"agencyBillPlan": {
"id": "bc:SJUcdT5ZdpnaoUXBqWFTs"
}
}
}
}