Working with producers

You can query for, create, and modify producers through Cloud API.

Querying for producers

Use the following endpoints to query for producers:
  • GET /billing/v1/producers
  • GET /billing/v1/producers/{producerId}

For example, the following GET request retrieves a single producer:

Command
GET /billing/v1/producers/bc:178
Response
{
    "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.

You can use a custom sort query parameter when querying for producers to sort the returned producers by producer tier:
  • /billing/v1/producers?sort=tier

Creating producers

Create a producer using the following endpoint:
  • 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.

Command
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"
            }
        }
    }
}