Public API: Overview

Public API

Quick Summary: Access Floship programmatically through the REST API to manage orders, products, inventory, and more.

Overview

The Floship Public API provides programmatic access to your account. Use it to create orders, manage products, check inventory, retrieve tracking information, and more — all through standard REST API calls.

The API is ideal for:

• Custom integrations — connect platforms not in the standard integration list
• Automation — build workflows that create orders or update products automatically
• Reporting — pull order and inventory data into your own systems
• Mobile apps — integrate Floship into your own applications

Quick Start

1. Navigate to Developers from your profile menu (top right)
2. Copy your Production Token from the credentials section
3. Click Explore to open the interactive API documentation
4. Try a test request using the examples in the documentation
5. Contact qa-testing+operations@floship.com if you need assistance

Accessing the API Documentation

1. Navigate to Developers from your profile menu
2. Click Explore to open the interactive API documentation in a new tab

The documentation includes:

• All available endpoints
• Request and response formats
• Authentication details
• Example requests

Note: If you don't see Developers in your menu, ask your company administrator to update your access.

Authentication

The API uses token-based authentication. Your credentials are available on the Developers page:

Include your token in the Authorization header of every request:

Authorization: Token YOUR_API_TOKEN

Warning: Keep your API token secure. Do not share it publicly or commit it to source code repositories. Regenerating a token invalidates the previous one — all integrations using the old token will stop working.

Key API Resources

Creating Forward Orders from Quarantine

When you create a forward order from quarantined return items, each order line can optionally include a return item condition. Use this when you have the same SKU in quarantine with different conditions and need to choose which condition should be forwarded.

In the order creation request:

• Set stock_type to quarantine
• Add condition to an order line when that line should use only quarantined items with that condition
• Leave condition blank or omit it when any quarantined item for that SKU can be used

The condition value must match one of your available return item condition codes. Standard condition codes include new, used, unset, damaged, damaged_packaging, expired, and cannot_decide. If your account uses custom return conditions, active custom condition codes available to your account can also be used.

Example order line:

{
  "item_sku": "SKU-001",
  "quantity": 2,
  "condition": "new"
}

If the condition is invalid or there are not enough quarantined items matching the requested SKU and condition, the API returns a validation error and the order is not created.

Webhooks

The API supports webhooks for real-time event notifications. Subscribe to events like order status changes, tracking updates, and inventory changes to receive instant notifications at your specified URL.

Webhook management is done via the API. See the API documentation for available webhook events, payload formats, and setup instructions.

Workflows

Workflow: Get Your API Token

When: You're setting up an integration and need your API credentials.

Steps:

1. Navigate to Developers from your profile menu (top right)
2. Copy the Production Token from the credentials section
3. Store the token securely in your integration's configuration

Result: Your integration can authenticate API requests using the token.

Workflow: Test API Requests in Sandbox

When: You want to test your integration without affecting live data.

Steps:

1. Navigate to Developers from your profile menu
2. Copy the Sandbox Token
3. Use the sandbox token and sandbox API URL in your test requests
4. Verify the responses match your expectations
5. Switch to the Production Token when ready to go live

Result: You can safely test API calls without affecting real orders or inventory.

Workflow: Create a Forward Order for a Specific Return Condition

When: You want to forward quarantined returned items, but only items with a specific condition should be selected.

Steps:

1. Confirm the returned items are in Quarantined status
2. Review the available condition code for the items you want to forward
3. Create an order with stock_type set to quarantine
4. Add condition to each order line that needs a specific return item condition
5. Submit the order creation request

Result: The forward order is created using only matching quarantined items for lines where condition was provided. Lines without condition can use any quarantined item for that SKU.

Workflow: Regenerate Your API Token

When: Your token may have been compromised, or you need a fresh token.

Steps:

1. Navigate to Developers from your profile menu
2. Click the regenerate button next to the token you want to replace
3. Confirm the regeneration — the old token is invalidated immediately
4. Update all integrations using the old token with the new one

Result: A new token is generated. The previous token no longer works.

Warning: All integrations using the old token will fail until updated with the new token.

Workflow: Set Up Webhook Notifications

When: You want to receive real-time notifications when events occur (e.g., order shipped).

Steps:

1. Review the webhook events in the API documentation (Developers → Explore)
2. Create a webhook subscription via the API, specifying the event type and your callback URL
3. Verify the webhook delivers test payloads to your endpoint
4. Handle incoming notifications in your application

Result: Your system receives automatic notifications when events occur, without polling the API.

Troubleshooting

Related Documentation

• Developers — API token management and developer access
• API Endpoint Reference — endpoint groups and payload reference
• Integrations Overview — connected platform setup and integration options

Support

For API questions, integration help, or to report issues:

• Email: qa-testing+operations@floship.com
• Review the interactive API documentation in your portal