# RevCent MCP Operation: `CreateFulfillmentAccount`

This document explains the `CreateFulfillmentAccount` operation in depth so MCP clients can correctly create Fulfillment Accounts in RevCent.

This is an operation-specific MCP guide. It explains how Fulfillment Accounts work, how they differ from Site Fulfillment Centers, how to securely collect fulfillment credentials, why shippable products must be associated with a Fulfillment Account, and how to validate a fulfillment setup before it is used in production.

Sources:
- RevCent API/MCP schema for `CreateFulfillmentAccount`
- RevCent API/MCP schema for `GetSiteFulfillmentCenters`
- RevCent API/MCP schema for `GetSiteFulfillmentCenter`
- RevCent API/MCP schema for `CreateSecureForm`
- RevCent API/MCP schema references for shippable product fulfillment assignment
- RevCent Fulfillment Overview

---

## Operation Summary

`CreateFulfillmentAccount` creates a new user Fulfillment Account and returns a unique `fulfillment_account_id`.

A Fulfillment Account is the user’s configured connection to a RevCent-supported Site Fulfillment Center.

Conceptually:

```text
Site Fulfillment Center = RevCent-supported provider/integration definition
Fulfillment Account = the user’s configured account/credentials for that provider
```

A Fulfillment Account is used by RevCent to know which fulfillment provider/account should receive shipment/order data for physical products.

---

# Required Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | The Fulfillment Account name. Must be unique from other Fulfillment Account names. |
| `fulfillment_center` | string | Yes | 20-character Site Fulfillment Center ID. Every user Fulfillment Account must be associated with a Site Fulfillment Center. |

---

# Optional Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `description` | string | No | Description of what the Fulfillment Account is for. |
| `enabled` | boolean | No | Whether the Fulfillment Account is enabled. |
| `secure_form_id` | string | No, but usually needed for credentialed providers | 20-character Secure Form ID used to securely provide fulfillment credentials/configuration. |

The schema has:

```json
"additionalProperties": false
```

Do not send unknown fields.

---

# Fulfillment Account vs Site Fulfillment Center

MCP must clearly understand the difference.

## Site Fulfillment Center

A Site Fulfillment Center is the RevCent-supported fulfillment provider/integration definition.

It answers:

```text
Which fulfillment providers or fulfillment integrations are available?
What required fields does this provider need?
```

Site Fulfillment Centers are retrieved using:

```text
GetSiteFulfillmentCenters
GetSiteFulfillmentCenter
```

A Site Fulfillment Center includes:

- Site fulfillment center ID
- Name
- Description
- Required fields

The user does not create Site Fulfillment Centers. RevCent exposes them.

---

## Fulfillment Account

A Fulfillment Account is the user-created connection to one selected Site Fulfillment Center.

It answers:

```text
Which user-specific provider account/configuration should RevCent use?
```

A Fulfillment Account includes:

- Fulfillment account ID
- Name
- Description
- Enabled status
- Associated Site Fulfillment Center
- Securely saved provider credentials/configuration
- Whether required fulfillment center fields have been saved
- Cancel-on-void behavior when retrieved

The user creates Fulfillment Accounts.

---

# Required Workflow Before Creating a Fulfillment Account

Before calling `CreateFulfillmentAccount`, MCP should follow this workflow:

```text
1. Determine what fulfillment provider/warehouse the user wants to use.
2. Call GetSiteFulfillmentCenters to list available Site Fulfillment Centers.
3. Select the correct Site Fulfillment Center.
4. Review the Site Fulfillment Center required fields.
5. Create a Secure Form using CreateSecureForm.
6. User completes the Secure Form with required provider credentials/configuration.
7. Once the user confirms the Secure Form is complete, call CreateFulfillmentAccount with secure_form_id.
8. Create the account disabled unless it is already verified and ready.
9. Verify fulfillment_center_fields_saved after creation if possible.
10. Associate all relevant shippable products with the new Fulfillment Account.
```

---

# Secure Form Requirement for Credentials

Fulfillment provider credentials are sensitive.

They may include:

- API keys
- Passwords
- Account IDs
- Client IDs
- Warehouse IDs
- Tokens
- Provider-specific identifiers
- Other required fulfillment configuration values

MCP should **never** ask the user to paste fulfillment credentials directly into chat or ordinary API request bodies.

Instead, create a Secure Form.

---

## CreateSecureForm for Fulfillment Credentials

Use:

```json
{
  "form_source": "fulfillment_center",
  "form_source_id": "SITE_FULFILLMENT_CENTER_ID"
}
```

Where:

```text
form_source = fulfillment_center
form_source_id = the selected 20-character Site Fulfillment Center ID
```

The response returns:

```text
secure_form_id
form_url
expiration date
completed status
```

The user should be directed to the `form_url` to complete the credential/configuration form.

After the user completes the form, use the `secure_form_id` in `CreateFulfillmentAccount`.

---

## Secure Form Expiration

A Secure Form is temporary.

Important:

```text
Secure Forms expire after 1 hour.
```

After expiration:

```text
The form URL is no longer valid.
The user cannot fill out the form.
Temporary saved data is deleted if the form was not completed.
```

MCP should tell the user to complete the form promptly.

If the form expires, create a new Secure Form.

---

## Completed Secure Forms Cannot Be Modified

Once a Secure Form is completed, its data is encrypted and saved internally by RevCent.

A completed Secure Form cannot be modified.

If credentials need to change later, create a new Secure Form and use `EditFulfillmentAccount`.

---

# `name`

The `name` is required and must be unique.

Use a clear name that identifies the fulfillment account’s provider, brand, store, region, warehouse, or purpose.

Good names:

```text
Brand A Fulfillment
Main Warehouse Fulfillment
US 3PL Fulfillment
WooCommerce Store A Fulfillment
Subscription Product Fulfillment
Brand B ShipBob Account
EU Warehouse Fulfillment
```

Poor names:

```text
Fulfillment
Account
Test
Warehouse
Provider
```

A generic name is risky when a RevCent account has multiple brands, stores, warehouses, or fulfillment providers.

---

# `description`

The `description` is optional but strongly recommended.

It should explain when this Fulfillment Account should be used.

A good description can include:

- Brand
- Store
- Website
- Product category
- Warehouse
- Region
- Fulfillment provider
- Production vs test status
- Operational notes
- Which shippable products should use it

Good example:

```text
Primary fulfillment account for Brand A physical products sold through the main WooCommerce store and shipped from the US warehouse.
```

Another example:

```text
EU warehouse fulfillment account for Brand B subscription refill products. Use only for shippable products sold through the EU storefront.
```

---

# `enabled`

`enabled` controls whether the Fulfillment Account is enabled.

Recommended setup behavior:

```json
"enabled": false
```

when initially creating the account.

Why create disabled first?

- Credentials may still need verification.
- Required fields may not be confirmed.
- Products may not yet be assigned.
- A test shipment or operational review may still be needed.
- The account may not be ready for production fulfillment.

Enable only after:

1. The user is ready for products assigned to this account to actually ship.
2. Secure Form is completed.
2. Required fields are saved.
3. Fulfillment provider configuration is verified.
4. Shippable products are assigned correctly.
5. The business is ready for shipments to route through this account.

---

---

# Critical Requirement: Fulfillment Account Must Be Enabled for Actively Sold Products

If a user is actively selling shippable products that are associated with a Fulfillment Account, that Fulfillment Account must be enabled.

A product may be correctly configured with:

```text
is_shippable = true
shipping_attributes.fulfillment_account = FULFILLMENT_ACCOUNT_ID
```

but if the associated Fulfillment Account is disabled, the product may not be shipped.

Conceptually:

```text
Customer buys shippable product
  ↓
Product points to Fulfillment Account
  ↓
Fulfillment Account is disabled
  ↓
Shipment may not be sent to fulfillment provider
  ↓
Product may not be shipped
```

This is critical for live ecommerce operations.

---

## MCP Guidance

When creating a Fulfillment Account, MCP should distinguish between setup/testing and active selling.

During setup:

```text
enabled = false
```

may be appropriate while credentials, required fields, product assignment, and fulfillment provider behavior are being verified.

Before the user actively sells products attached to that Fulfillment Account:

```text
enabled must be true
```

The MCP should explicitly remind the user:

```text
Before actively selling products assigned to this Fulfillment Account, enable the Fulfillment Account or those products may not ship.
```

---

## Active Selling Checklist

Before a shippable product is actively sold:

1. Product is marked `is_shippable = true`.
2. Product has `shipping_attributes.fulfillment_account`.
3. The assigned Fulfillment Account exists.
4. The assigned Fulfillment Account is enabled.
5. Required fulfillment center fields are saved.
6. Provider credentials/configuration are valid.
7. Product routing matches the intended brand, store, provider, warehouse, or region.

A disabled Fulfillment Account should only be used for setup, testing, migration, or intentionally paused fulfillment.


# `fulfillment_center`

`fulfillment_center` is required.

It is the 20-character Site Fulfillment Center ID.

Example:

```json
"fulfillment_center": "XXXXXXXXXXXXXXXXXXXX"
```

MCP should not guess this ID.

Use:

```text
GetSiteFulfillmentCenters
```

to retrieve available Site Fulfillment Centers and their IDs.

Use:

```text
GetSiteFulfillmentCenter
```

to retrieve details about a specific Site Fulfillment Center, including its required fields.

---

# `secure_form_id`

`secure_form_id` is a 20-character Secure Form ID.

Example:

```json
"secure_form_id": "YYYYYYYYYYYYYYYYYYYY"
```

Use `secure_form_id` to attach securely submitted provider credentials/configuration to the Fulfillment Account.

This is intended for MCP use so users do not submit sensitive fulfillment credentials via AI or normal request bodies.

MCP should include `secure_form_id` when the selected Site Fulfillment Center requires user-specific credentials/configuration.

---

# Why Fulfillment Accounts Must Be Associated With Shippable Products

Creating a Fulfillment Account is only part of fulfillment setup.

The Fulfillment Account must also be associated with the relevant shippable products.

In RevCent product configuration, products can be marked:

```text
is_shippable = true
```

When a product is shippable, its shipping attributes should include:

```text
shipping_attributes.fulfillment_account
```

This value is the 20-character Fulfillment Account ID.

The product association is what tells RevCent which configured provider/account should handle that product when sold.

Conceptually:

```text
Product is shippable
  ↓
Product has shipping_attributes.fulfillment_account
  ↓
Sale occurs
  ↓
RevCent knows which Fulfillment Account should handle shipment
  ↓
Fulfillment provider receives the order/shipping details
```

Without this association, RevCent may not know where to send the fulfillment request or which provider credentials/configuration should be used.

---

## Strong MCP Rule

After creating a Fulfillment Account, MCP should remind the user:

```text
All relevant shippable products must be associated with this Fulfillment Account.
```

This is not optional for operational fulfillment.

A Fulfillment Account that is not associated with shippable products may exist, but it will not route product shipments unless products are configured to use it.

---

## Product-Level Fulfillment Routing

Product-level fulfillment assignment allows RevCent to route fulfillment based on the product sold.

Examples:

```text
Brand A Supplement → Brand A Fulfillment Account
Brand B Skincare Product → Brand B Fulfillment Account
US Product → US Warehouse Fulfillment Account
EU Product → EU Warehouse Fulfillment Account
Subscription Refill Product → Subscription Fulfillment Account
```

This is especially important for accounts with multiple:

- Brands
- Websites
- Stores
- Warehouses
- Regions
- Fulfillment providers
- Product lines
- Subscription/trial product flows

---

## Bundles and Shippable Components

RevCent products can also be bundles.

For bundles, fulfillment may depend on how the bundle is unbundled.

If a bundle contains physical products, every shippable component should have correct fulfillment configuration.

Conceptually:

```text
Bundle product sold
  ↓
Bundle is unbundled based on configuration
  ↓
Individual shippable products are identified
  ↓
Each shippable component must route to the correct Fulfillment Account
```

MCP should not assume that assigning fulfillment only at a parent bundle level is enough unless the product configuration supports that intended behavior.

---

# Fulfillment Account Readiness

A Fulfillment Account is ready for operational use only when:

```text
Fulfillment Account exists
Fulfillment Account is associated with correct Site Fulfillment Center
Secure credentials/configuration are saved
Required fulfillment center fields are saved
Fulfillment Account is enabled
Relevant shippable products are assigned to it
```

The retrieved Fulfillment Account includes:

```text
fulfillment_center_fields_saved
```

If this is false, the account may not be ready.

MCP should use `EditFulfillmentAccount` with a new Secure Form if required fields are not saved.

---

# Tracking Numbers and Shipment Updates

Once products are properly associated and fulfillment is operational, RevCent can receive shipment-related updates from the user’s Fulfillment Account, such as:

- Tracking number
- Tracking URL
- Shipping provider
- Shipping method
- Shipped status
- Ship date
- Shipment-related status

Tracking numbers and tracking URLs can be used by:

- RevCent users
- Customer support teams
- Customers
- Email Templates
- AI Assistants
- AI Voice Agents
- Functions
- External systems

Delivery-status updates, such as knowing when a package was delivered, require an EasyPost or Shippo third-party integration if the user wants delivery visibility inside RevCent.

---

# `cancel_on_void`

`cancel_on_void` appears when retrieving a Fulfillment Account.

It controls whether RevCent should automatically contact the fulfillment center and cancel a shipment if the shipment is fully refunded and/or voided in RevCent.

The schema recommends this be true.

This matters because a fully refunded or voided order may no longer need to ship.

Benefits:

- Avoid shipping cancelled orders
- Avoid unnecessary fulfillment cost
- Reduce customer confusion
- Reduce support issues
- Avoid inventory issues
- Prevent products from being sent after payment reversal

Although `CreateFulfillmentAccount` does not expose `cancel_on_void` as an input field in the create schema, MCP should understand its importance when reviewing retrieved Fulfillment Account settings.

---

# Example Request: Create Disabled Fulfillment Account With Secure Form

```json
{
  "name": "Brand A US Fulfillment",
  "description": "Primary fulfillment account for Brand A physical products sold through the main US store.",
  "enabled": false,
  "fulfillment_center": "XXXXXXXXXXXXXXXXXXXX",
  "secure_form_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

---

# Example Request: Minimal Create

```json
{
  "name": "Brand A Fulfillment",
  "fulfillment_center": "XXXXXXXXXXXXXXXXXXXX"
}
```

This minimal request is schema-valid, but it may not be operational if the Site Fulfillment Center requires credentials/configuration and no `secure_form_id` is supplied.

---

# Recommended MCP Creation Process

Before calling `CreateFulfillmentAccount`, MCP should determine:

1. Which fulfillment provider or warehouse the user wants to use.
2. Which Site Fulfillment Center corresponds to that provider.
3. Whether the Site Fulfillment Center has required fields.
4. Whether a Secure Form must be created.
5. Whether the user completed the Secure Form.
6. What the Fulfillment Account should be named.
7. What the description should say.
8. Whether the account should start disabled.
9. Which shippable products should later be associated with this account.
10. Whether this account is for a brand, website, store, warehouse, region, or product line.
11. Whether EasyPost or Shippo is needed for delivered-status updates.
12. Whether the user understands product assignment is required for fulfillment routing.

---

# Validation Checklist

Before submitting `CreateFulfillmentAccount`:

1. `name` is present.
2. `name` is unique.
3. `fulfillment_center` is present.
4. `fulfillment_center` is a 20-character Site Fulfillment Center ID.
5. The Site Fulfillment Center was selected from `GetSiteFulfillmentCenters` or verified with `GetSiteFulfillmentCenter`.
6. Required Site Fulfillment Center fields were reviewed.
7. If credentials/configuration are required, `CreateSecureForm` was used.
8. If `secure_form_id` is included, it is 20 characters.
9. Credentials were not pasted into chat or ordinary request body fields.
10. `description` explains the account purpose.
11. `enabled` is intentionally set.
12. If products assigned to this account are actively being sold, `enabled` must be true or products may not ship.
12. If uncertain, the account starts disabled.
13. The user knows all relevant shippable products must be associated with this Fulfillment Account.
14. The user knows product association is done through `shipping_attributes.fulfillment_account`.
15. The fulfillment routing strategy matches brand/store/warehouse/provider/region needs.
16. No unknown fields are included.

---

# Common Mistakes

## Mistake: Confusing Site Fulfillment Center With Fulfillment Account

Wrong:

```text
The user creates a Site Fulfillment Center.
```

Correct:

```text
The user selects a Site Fulfillment Center and creates a Fulfillment Account connected to it.
```

---

## Mistake: Asking for Credentials in Chat

Wrong:

```text
Please paste your fulfillment provider API key here.
```

Correct:

```text
Create a Secure Form and have the user enter credentials there.
```

---

## Mistake: Creating a Fulfillment Account but Not Assigning Products

Wrong:

```text
Create Fulfillment Account and assume fulfillment is ready.
```

Correct:

```text
Create Fulfillment Account, verify required fields are saved, then associate all relevant shippable products with shipping_attributes.fulfillment_account.
```

---

## Mistake: Enabling Before Verification

Wrong:

```json
"enabled": true
```

before credentials and product assignments are verified.

Correct:

```json
"enabled": false
```

until setup is verified.

---

## Mistake: Generic Fulfillment Account Names

Wrong:

```text
Fulfillment
```

Correct:

```text
Brand A US Fulfillment
```

---

# Output Schema

Successful response:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "fulfillment_account_id": "YYYYYYYYYYYYYYYYYYYY",
  "result": "..."
}
```

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `fulfillment_account_id` | 20-character Fulfillment Account ID created by the operation. |
| `result` | Human-readable result message. |

---

# Quick Reference

Recommended request:

```json
{
  "name": "Brand A US Fulfillment",
  "description": "Primary fulfillment account for Brand A physical products sold through the US warehouse.",
  "enabled": false,
  "fulfillment_center": "XXXXXXXXXXXXXXXXXXXX",
  "secure_form_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

Most important rules:

```text
CreateFulfillmentAccount requires name and fulfillment_center.
fulfillment_center is a Site Fulfillment Center ID, not a user Fulfillment Account ID.
Use GetSiteFulfillmentCenters to choose the correct Site Fulfillment Center.
Use CreateSecureForm for sensitive fulfillment credentials.
Do not collect credentials in chat.
Create disabled first unless setup is already verified.
After creation, associate every relevant shippable product with this Fulfillment Account, and ensure the account is enabled before those products are actively sold.
Shippable products should use shipping_attributes.fulfillment_account.
A Fulfillment Account is not operationally useful for product shipping unless shippable products are assigned to it, and those products may not ship if the assigned Fulfillment Account is disabled.
```


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.