# Get started

To use the Origin Schedule Configuration API, you can follow the instructions on this page. More information about the Origin Schedule Configuration API can be found in [Configuration APIs](https://docs.shipium.com/docs/configuration-apis). In addition, if you prefer to configure your origin schedules via the [Shipium Console](https://partner.shipium.com/login), you can find guidance for doing so in the [Origin Schedule](https://docs.shipium.com/docs/origins#origin-schedule) documentation.

> ### Warning: potential negative impact on your fulfillment operations  
> This API can modify elements of your organization's network fulfillment configuration in ways that could negatively impact the production of your fulfillment operations. You should only use the API if you are familiar with how any changes you make could affect your network fulfillment configuration.

# Configure origin schedules with the Origin Schedule Configuration API

The Origin Schedule Configuration API assumes you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication). The general endpoint for Origin Configuration calls is included in the table below.

| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}/schedule/entry` |

### Authentication for API calls  
In the cURL examples on this page, the environment variable `AUTHSTRING` is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

## Request fields for API calls  
The following tables provide the required and optional fields for calling the Origin Schedule Configuration API. Path elements are described for each use case in the sections that follow.

### Required request fields

| Request field | Details |
| --- | --- |
| `carrierSchedules.carrierId` | **Type:** String<br>**Description:** Internal carrier account ID as represented in Shipium; see [Supported Carriers](https://docs.shipium.com/docs/supported-carriers) for carrier IDs. |
| `carrierSchedules.cutoffExceptions.date` | **Type:** String<br>**Example:**`2022-12-24`<br>**Description:** The date with the changed cutoff time |
| `carrierSchedules.cutoffTimes.cutoff` | **Type:** String<br>**Description:** The final time when a shipment for a carrier or shipment method departs for the specified day |
| `carrierSchedules.cutoffTimes.dayOfWeek` | **Type:** String (enumeration)<br>**Values:**`Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`<br>**Description:** The day of the week to which this cutoff applies |
| `from` | **Type:** String<br>**Description:** Date of the starting boundary of the active schedule |
| `holidays.date` | **Type:** String<br>**Example:**`2020-07-04`<br>**Description:** The date of the holiday |
| `processingCutoff.expectedDaysToShip` | **Type:** Integer (int32)<br>**Description:** The number of days that are needed for a fulfillment center to process a shipment |
| `processingCutoff.expectedDaysAndTimeToShip` | **Type:** Float<br>**Description:** The number of days, expressed as a decimal, that are needed for a fulfillment center to process a shipment. Use this field for sub-day precision (e.g., 0.75 represents 18 hours). When both `expectedDaysToShip` and `expectedDaysAndTimeToShip` are provided, Shipium prioritizes `expectedDaysAndTimeToShip`. |
| `processingCutoff.shippingCutoff` | **Type:** String<br>**Example:**`13:45`<br>**Description:** The time after which requests will need an additional day for processing; accepts ISO-8601 time format (`HH:mm` or `HH:mm:ss`) |
| `processingCutoff.weekendCutoff` | **Type:** String<br>**Example:**`10:30`<br>**Description:** When present, overrides the cutoff time for weekend days; accepts ISO-8601 time format (`HH:mm` or `HH:mm:ss`) |
| `shippingDays` | **Type:** String (enumeration)<br>**Values:**`Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`<br>**Description:** List of days on which to ship |
| `to` | **Type:** String<br>**Description:** Date of the end boundary of the active schedule |

### Optional request fields

| Request field | Details |
| --- | --- |
| `carrierSchedules.carrierScheduleId` | **Type:** String<br>**Description:** Identifier used to refer to a specific carrier schedule; if you do not provide this value, a unique ID will be generated. Uniqueness is guaranteed; if two IDs collide, one of them will be updated to a unique ID. |
| `carrierSchedules.carrierServiceMethodIds` | **Type:** String<br>**Description:** The set of carrier service methods that should use this schedule; each item in this list must map to an internal Shipium ID that represents a carrier service method. If this is `null` or empty, all of this carrier's shipment methods without a schedule will use this schedule. See [Supported Carriers](https://docs.shipium.com/docs/supported-carriers) for carrier service method IDs. |
| `carrierSchedules.cutoffExceptions.cutoff` | **Type:** String<br>**Description:** Specifies dates when either no service is available or a different cutoff should be used instead of the one specified in cutoff times |
| `holidays.metadata.additionalProp1` | **Type:** String<br>**Description:** A map of properties to save along with this date |

## Create an origin schedule entry  
The endpoint for creating an origin schedule entry is provided below.

### Path  
**POST**`https://api.shipium.com/api/v1/partnerConfiguration/origins`

**Required path element:**`originId` (a string ID for the origin with which this schedule entry is to be associated at creation)

### Example cURL call  
This example shows a request to create an origin schedule:

```curl
curl --request POST \
  --url https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}/schedule/entry \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT CONTENTS FROM BELOW'
```

### Example request body  
This example shows the JSON request:

```json
{
  "carrierSchedules": [
    {
      "carrierId": "usps",
      "carrierScheduleId": "usps-reno-fc-schedule",
      "carrierServiceMethodIds": [
        "usps-ground-advantage-service-method, usps-priority-mail-service-method"
      ],
      "cutoffExceptions": [
        {
          "cutoff": "15:30",
          "date": "2022-12-24"
        }
      ],
      "cutoffTimes": [
        {
          "cutoff": "13:45",
          "dayOfWeek": "friday"
        }
      ]
    }
  ],
  "from": "2023-05-23T19:51:31.175Z",
  "holidays": [
    {
      "date": "2020-07-04",
      "metadata": {
        "additionalProp1": "Floating"
      }
    }
  ],
  "processingCutoff": {
    "expectedDaysToShip": 0,
    "expectedDaysAndTimeToShip": 0,
    "shippingCutoff": "13:45",
    "weekendCutoff": "10:30"
  },
  "shippingDays": [
    "friday"
  ],
  "to": "2023-05-23T19:51:31.175Z"
}
```

### Example response body  
```json
{
  "carrierSchedules": [
    {
      "carrierId": "usps",
      "carrierScheduleId": "usps-reno-fc-schedule",
      "carrierServiceMethodIds": [
        "usps-ground-advantage-service-method, usps-priority-mail-service-method"
      ],
      "cutoffExceptions": [
        {
          "cutoff": "15:30",
          "date": "2022-12-24"
        }
      ],
      "cutoffTimes": [
        {
          "cutoff": "13:45",
          "dayOfWeek": "friday"
        }
      ]
    }
  ],
  "from": "2023-05-23T20:07:04.353Z",
  "holidays": [
    {
      "date": "2020-07-04",
      "metadata": {
        "additionalProp1": "Floating"
      }
    }
  ],
  "orchestratedAssetMetadata": {
    "orchestrationId": "4ad3b5d5-f256-4184-b9af-15ccca60ea99",
    "orchestrationTimeStamp": "2023-05-23T20:07:04.353Z"
  },
  "processingCutoff": {
    "expectedDaysToShip": 0,
    "expectedDaysAndTimeToShip": 0,
    "shippingCutoff": "13:45",
    "weekendCutoff": "10:30"
  },
  "scheduleEntryId": "7fc6c76b-e681-4ce0-80ce-e439b76d3977",
  "shippingDays": [
    "friday"
  ],
  "to": "2023-05-23T20:07:04.353Z"
}
```

## Retrieve all origin schedules for an origin  
### Path  
**GET**
`https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}/schedule`

**Required path element** : `originId` (a string ID for the origin with which this schedule entry is associated)

### Example response body  
```json
{
  "orchestratedAssetMetadata": {
    "orchestrationId": "8205a8b7-1f69-4479-b559-731d309beb60",
    "orchestrationTimeStamp": "2023-05-23T20:10:39.342Z"
  },
  "results": [
    {
      "carrierSchedules": [
        {
          "carrierId": "usps",
          "carrierScheduleId": "usps-reno-fc-schedule",
          "carrierServiceMethodIds": [
            "usps-ground-advantage-service-method, usps-priority-mail-service-method"
          ],
          "cutoffExceptions": [
            {
              "cutoff": "15:30",
              "date": "2022-12-24"
            }
          ],
          "cutoffTimes": [
            {
              "cutoff": "13:45",
              "dayOfWeek": "friday"
            }
          ]
        }
      ],
      "from": "2023-05-23T20:10:39.342Z",
      "holidays": [
        {
          "date": "2020-07-04",
          "metadata": {
            "additionalProp1": "Floating"
          }
        }
      ],
      "orchestratedAssetMetadata": {
        "orchestrationId": "8205a8b7-1f69-4479-b559-731d309beb60",
        "orchestrationTimeStamp": "2023-05-23T20:10:39.342Z"
      },
      "processingCutoff": {
        "expectedDaysToShip": 0,
        "expectedDaysAndTimeToShip": 0,
        "shippingCutoff": "13:45",
        "weekendCutoff": "10:30"
      },
      "scheduleEntryId": "b6268dd4-0c89-4d4c-848c-9b51f817da98",
      "shippingDays": [
        "friday"
      ],
      "to": "2023-05-23T20:10:39.342Z"
    }
  ]
}
```

## Delete an origin schedule entry by schedule entry ID  
### Path  
**DELETE**
`https://api.shipium.com/api/v1/partnerConfiguration/origins/{originId}/schedule/entry/{originScheduleEntryId}`

**Required path element**: `originId` (a string ID for the origin with which this schedule entry is associated)

**Required path element**: `originScheduleEntryId` (a string ID for the origin schedule entry with which this schedule entry is associated)

### Example response body  
```json
{
  "carrierSchedules": [
    {
      "carrierId": "usps",
      "carrierScheduleId": "usps-reno-fc-schedule",
      "carrierServiceMethodIds": [
        "usps-ground-advantage-service-method, usps-priority-mail-service-method"
      ],
      "cutoffExceptions": [
        {
          "cutoff": "15:30",
          "date": "2022-12-24"
        }
      ],
      "cutoffTimes": [
        {
          "cutoff": "13:45",
          "dayOfWeek": "friday"
        }
      ]
    }
  ],
  "from": "2023-05-23T20:13:58.563Z",
  "holidays": [
    {
      "date": "2020-07-04",
      "metadata": {
        "additionalProp1": "Company_wide"
      }
    }
  ],
  "orchestratedAssetMetadata": {
    "orchestrationId": "3f1b036b-4ec3-48c3-be18-8a261364f02c",
    "orchestrationTimeStamp": "2023-05-23T20:13:58.563Z"
  },
  "processingCutoff": {
    "expectedDaysToShip": 0,
    "expectedDaysAndTimeToShip": 0,
    "shippingCutoff": "13:45",
    "weekendCutoff": "10:30"
  },
  "scheduleEntryId": "ae73cc23-7146-4b2c-ab2b-d91be4ce884e",
  "shippingDays": [
    "friday"
  ],
  "to": "2023-05-23T20:13:58.563Z"
}
```

## Update an existing origin schedule  
Making updates to an existing origin schedule is currently managed by [deleting the existing origin schedule](https://docs.shipium.com/docs/origin-schedule-configuration-api#delete-an-origin-schedule-entry-by-schedule-entry-id) and [creating a new origin schedule](https://docs.shipium.com/docs/origin-schedule-configuration-api#create-an-origin-schedule-entry).

# Resources  
Your Shipium team member is available to help along the way. However, you might find these resources helpful:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)