---
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Spend & Expense API redesign

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

| Endpoint                                               | Description                                                                                                       |
| :----------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| `PUT /v3/spend/budgets/{budgetId}/members/bulk`        | Update a list of budget members in a budget. For more than 5 users, the request will be processed asynchronously. |
| `GET /v3/spend/budgets/{budgetId}/members/{userId}`    | Get a member in a budget                                                                                          |
| `PUT /v3/spend/budgets/{budgetId}/members/{userId}`    | Update a member in a budget                                                                                       |
| `DELETE /v3/spend/budgets/{budgetId}/members/{userId}` | Delete a member from a budget                                                                                     |

## Deleted endpoints

| Endpoint                                                                |
| :---------------------------------------------------------------------- |
| `PATCH /v3/spend/budgets/{budgetId}/userAllocations/{userAllocationId}` |
| `GET /v3/spend/budgets/{budgetId}/userAllocations/{userAllocationId}`   |
| `PATCH /v3/spend/budgets/{budgetId}/users`                              |

## General updates

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Change
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Renamed
      </td>

      <td>
        The `periodInterval` field is renamed to `recurringInternal`\
        The `limitless` field is renamed to `limitlessOverspend`
      </td>
    </tr>

    <tr>
      <td>
        Added
      </td>

      <td>
        `recurringInterval`: Budget funds reset interval\
        `overspendBuffer`: Amount over the budget limit before transactions are declined
      </td>
    </tr>

    <tr>
      <td>
        Removed
      </td>

      <td>
        The `type` field is removed. Use `recurringInterval` instead.
      </td>
    </tr>
  </tbody>
</Table>

## GET /v3/spend/budgets

| Change  | Description                                                                                |
| :------ | :----------------------------------------------------------------------------------------- |
| Added   | Sorting and filtering operations are now consistent with other BILL v3 API list operations |
| Removed | The `type` field is removed. You can continue filtering with this field.                   |

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

| Change  | Description                                                                                                              |
| :------ | :----------------------------------------------------------------------------------------------------------------------- |
| Renamed | The `GET /v3/spend/budgets/{budgetId}/userAllocations` endpoint is renamed to `GET /v3/spend/budgets/{budgetId}/members` |
| Added   | Sorting and filtering operations are now consistent with other BILL v3 API list operations                               |
| Removed | The `retired` field is removed. You can continue filtering with this field.                                              |

# Cards operation updates

## New endpoint

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Endpoint
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `GET /v3/spend/cards/{cardId}/pan-jwt`
      </td>

      <td>
        Get a JWT token for retrieving a card's PAN (full account number).  

        The JWT token contains all the information required for retrieving details about a virtual card (16-digit PAN, CVV, and expiration date). The JWT token lifespan is 5 minutes.
      </td>
    </tr>
  </tbody>
</Table>

## Deleted endpoint

| Endpoint                                                                               |
| :------------------------------------------------------------------------------------- |
| `GET /v3/spend/cards/getPanToken/{token}` (See `GET /v3/spend/cards/{cardId}/pan-jwt`) |

## General updates

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Change
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Renamed
      </td>

      <td>
        The `amount` field is renamed to `limit`
      </td>
    </tr>

    <tr>
      <td>
        Added
      </td>

      <td>
        The `limit`, `shareBudgetFunds`, and `recurringLimit` fields are moved from the user allocation logic
      </td>
    </tr>

    <tr>
      <td>
        Removed
      </td>

      <td>
        The `budgetAllocation` field is removed. You can use `budgetId` for this information.\
        The `isPhysical` field is removed. You can use `type` for this information.\
        The `token` field is removed. See `GET /v3/spend/cards/{cardId}/pan-jwt` for more information.
      </td>
    </tr>
  </tbody>
</Table>

## GET /v3/spend/cards

| Change  | Description                                                                                     |
| :------ | :---------------------------------------------------------------------------------------------- |
| Added   | Sorting and filtering operations are now consistent with other BILL v3 API list operations      |
| Removed | The `userIds` field is removed as a body parameter. You can continue filtering with this field. |

## PATCH /v3/spend/cards/\{cardId}

| Change | Description                                                                        |
| :----- | :--------------------------------------------------------------------------------- |
| Added  | The user allocation update logic is now a part of `PATCH /v3/spend/cards/{cardId}` |

# Transactions operation updates

## General updates

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Change
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Renamed
      </td>

      <td>
        The `receiptSyncStatusType` field is renamed to `receiptSyncStatus`.\
        The `receiptStatusType` field is renamed to `receiptStatus`.\
        The `companyProgramNetworkName` field is renamed to `network`.\
        The `hasAllRequiredFieldsCompleted` field is renamed to `complete`.
      </td>
    </tr>

    <tr>
      <td>
        Removed
      </td>

      <td>
        The `cleanedMerchantName` field is removed. You can use `merchantName` for this information.\
        The `declineDetails` field is removed. You can use `declineReason` for this information.
      </td>
    </tr>
  </tbody>
</Table>

# Other updates

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