# Assign Bundles
source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md

#### Overview {#overview}

**Actors:** Issuer developer, Mastercard Global Benefits Platform  

**Preconditions:** Card exists and is associated to the ICA; the specified bundle(s) have been pre-configured by Mastercard for the ICA; the bundle is not already active on the card  

**Outcome:** The specified bundles are assigned to the card and returned with their effective and expiry dates  

**Endpoint:** `POST /card-bundles` --- use this endpoint to add one or more individual bundles directly to a card; use [Assign Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md) if the cardholder should receive a pre-configured set of bundles managed through a segment

Assigns benefits to a card by accepting a list of bundles that will be assigned to the PAN number, along with an effective date and an optional expiry date in the input. The response is an array of bundles that are assigned to the card. The benefit allocation assign bundle service can:
Diagram assign_bundles
API Reference: `POST /card-bundles`

### Use Case 1: assign bundle to a card {#use-case-1-assign-bundle-to-a-card}

1. Cardholder requests a new benefit be associated with their card.
2. Issuer sends a request with a list of bundles that will be assigned to the PAN number, along with an effective date and an optional expiry date as input parameters.
3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains benefit bundle codes assigned with effective and expiry dates of bundles.

### Use Case 2: bundle with future effective date {#use-case-2-bundle-with-future-effective-date}

1. Cardholder requests a new benefit be associated with their card.
2. Issuer sends a request with a list of bundles that will be assigned to the PAN number, along with an effective date and an optional expiry date as input parameters.
3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains benefit bundle codes assigned with effective and expiry dates, bundle code with the future effective date will be applied with the future effective date.

### Use Case 3: bundle that has been expired in the past {#use-case-3-bundle-that-has-been-expired-in-the-past}

1. Cardholder requests a new benefit be associated with their card.
2. Issuer sends a request with a list of bundles that will be assigned to the PAN number, along with an effective date and an optional expiry date as input parameters.
3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains benefit bundle codes assigned with effective and expiry dates, the expired bundle is not added.

### Use Case 4: bundle with a future expiry date {#use-case-4-bundle-with-a-future-expiry-date}

1. Cardholder requests a new benefit be associated with their card.
2. Issuer sends a request with a list of bundles that will be assigned to the PAN number, along with an effective date and an optional expiry date as input parameters.
3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains benefit bundle codes assigned with effective and expiry dates, future expiration dates will get the future expiration date applied.

### Example Request \& Response {#example-request--response}

**Request** (`POST /card-bundles`):

```json
{
  "cardNumber": 5291070000000000,
  "bundles": [
    {
      "code": "080815",
      "effectiveDate": "2023-08-08",
      "expiryDate": "2024-07-24"
    }
  ]
}
```

**Sandbox response** (`200 OK`):
Note: The Sandbox returns a fixed generic mock response regardless of input values. Use MTF for real data validation.

```json
{
  "bundles": [
    {
      "code": "080815",
      "effectiveDate": "2023-08-08",
      "expiryDate": "2024-07-24"
    },
    {
      "code": "087524",
      "effectiveDate": "2023-08-08",
      "expiryDate": "2024-07-24"
    }
  ]
}
```

### Error Notes {#error-notes}

| **Error Code** |                      **Description**                      |                                       **Recovery Action**                                        |
|----------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| `37`           | Required field missing, Card Number                       | Include `cardNumber` in the plaintext payload before encrypting                                  |
| `40`           | Required field missing, Effective Date                    | Include `bundles[].effectiveDate` in the plaintext payload before encrypting                     |
| `48`           | Expiry date cannot be before effective date               | Ensure `expiryDate` (if supplied) is on or after `effectiveDate`                                 |
| `51`           | Not authorized to allocate benefits for given card number | Confirm the API key is authorized for the ICA that owns the card                                 |
| `57`           | Invalid encryption key                                    | Re-download your encryption certificate from the project dashboard and update your configuration |
| `58`           | Signature verification failed                             | Verify the mTLS certificate, signing key, and encrypted request body before resending            |

## Additional Information {#additional-information}

1. Look at the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for information on how to implement this use case.
2. Look at the [Code and Formats](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md) for acknowledgement responses.