In the payments API response, you now receive information about the bills that a payment amount is applied to.

When you pay a bill with POST /v3/payments or when you pay multiple bills with one POST /v3/payments/bulk, you now see a billPayments object in the response. For each bill payment, the billPayment object includes the bill payment id, bill id, and amount applied to the bill.

See Payments for more information.

BILL is introducing a more stable sandbox environment for you to continue testing with the BILL v2 API - https://api-stage.bill.com/api/v2/. In addition, we have migrated the developer keys of all current API customers to the new environment.

On August 31, 2024, BILL will sunset the current sandbox environment. To continue testing with the BILL v2 API, set up a test organization in the new environment and start making your v2 API calls with the new base URL. See the next set of sections in this email for more information.

📘

NOTE

August 31, 2024 onwards, after the current sandbox environment is sunset, your test data in the current sandbox environment will not be available.

This change does not affect any integrations in the BILL production environment.

URL changes

The API base URL and web app URL is changing as part of introducing the new sandbox environment.

Developer actions

Now that the developer key migration is complete, you can take advantage of testing with the new sandbox environment.

Complete the provided set of recommended steps.

1. Sign up and create a new BILL developer account at https://www-test.bill.com/signup?env=stage. Make sure that you enter the email address you use for your current sandbox developer account.
2. Select Accounts Payable & Receivable and click Get Started to complete your BILL account activation flow. This includes adding a valid phone number for the two-step verification process.
3. When your sign-up is complete, you land on the Get started section. You can continue testing with BILL features. For example, adding a vendor, bill, customer, and invoice.
4. At any point, you can sign in to your developer account at https://login.stage.us.bill.com/neo/login with your created user name (email address) and password.

API sign in credentials

Set the required fields to sign in with /v2/Login.json.

Sample /v2/ListOrgs.json request

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/ListOrgs.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={email_address}' \
--data 'password={password}' \
--data 'devKey={developer_key}'

Sample /v2/Login.json request

curl --request POST \
--url 'https://api-stage.bill.com/api/v2/Login.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={username}' \
--data 'password={password}' \
--data 'devKey={developer_key}' \
--data 'orgId={organization_id}'

After signing in, you can continue testing with BILL v2 API operations, including adding a vendor, creating a bill, and submitting a payment. For questions or concerns, email us at [email protected].

We have added pagination in the get list of event notifications (GET /v3/events/subscription/{subscriptionId}) and get list of subscriptions (GET /v3/subscriptions) endpoints.

See Get list of event notifications and Get list of subscriptions for more information.

We have made a set of improvements in the BILL webhook notification payloads for consistency with other BILL v3 API responses.

• The createdTime and updatedTime value format is now consistent with the format in other BILL v3 API responses. The format is yyyy-MM-dd'T'HH:mm:ss.SSSX. For example, 2024-12-15T22:53:15.127+00:00.
• In the notification payloads for bills, the invoiceNumber and invoiceDate information is now in the invoice object. This matches the format of the /v3/bills API response.

See Webhooks for more information.

We have introduced a new API endpoint for getting organization price plan details. A BILL price plan for an organization provides a range of information, including monthly subscription fees and the terms and conditions for additional charges in the price plan.

In the Guides section documentation for creating an international vendor, we have added more examples for working with regulatoryFields. We now have examples for Brazil and Australia with instructions for working with regulatoryFields and payment information.

See Creating an international vendor for more information.

We have introduced a set of API endpoints for adding a phone for a user. You can also check whether a phone number has been added for the user. BILL requires users to have a linked phone number for initiating risk verification for an organization.

We are excited to announce a customer-focused redesign for the Spend & Expense API endpoints. The core of the changes are about further simplifying the /v3/spend/budgets API endpoints. In addition, we have introduced many quality of life updates and simplifications in other Spend & Expense API endpoints.

Our expectations with the redesign are that the terminology and experience will now be closer for customers who are familiar with the web app experience.

Budgets operation updates

New endpoints

Deleted endpoints

General updates

GET /v3/spend/budgets

GET /v3/spend/budgets/{budgetId}/members

Cards operation updates

New endpoint

Deleted endpoint

General updates

GET /v3/spend/cards

PATCH /v3/spend/cards/{cardId}

Transactions operation updates

General updates

Other updates

All date-time fields are consistent across all BILL v3 API endpoints. For example, deletedAt is renamed to deletedTime.

In the Guides section documentation for creating an international vendor, we learned that there was a need for further explaining the use of paymentPurpose and regulatoryFields. These objects are required in your request for enabling payments to international vendors.

We have updated the documentation with examples of international vendor locations like Brazil and Austria with instructions for setting paymentPurpose and regulatoryFields.

See Creating an international vendor for more information.

In the payment webhook notification payload, you now receive descriptive status and type names instead of a numeric code. The payment status, funding account type, and disbursement type values have been updated.

See Payment webhook notification payloads for more information.