App guides
The Cropster app sends your coffee products and orders from Swell to Cropster, the roasting software, for roast production planning. Each paid order becomes a Cropster production order, and the order's production state is copied back to Swell.
| When | What the app does |
| A product or one of its variants is created or updated | Sends the product to Cropster with one variant for each active variant that has a SKU and a package size. |
| An order is paid, or submitted if you choose | Sends the order to Cropster as a production order, with the SKU and quantity of each coffee item. |
| The items of an open order change | Sends the order again, while Cropster still has it open. |
| Every 15 minutes | Copies the state of orders changed in Cropster to their Swell orders: Open, Scheduled, In progress, Roasted or Completed. |
| You sync from the Cropster sync page | Sends your existing products or orders, one page at a time, and lists any record that wasn't sent with the reason. |
- A Cropster account with the API Integration add-on, which lets you create service accounts. To get the add-on, contact Cropster at api@cropster.com.
- Coffee products with a SKU on each variant and a package size Cropster recognizes, such as 250g, 12 oz, 1 kg or 2 lb.
Install Cropster from the Swell App Store, and set it up in your test environment before the live one.
Create a service account
In Cropster, click the gear icon at the top right and go to Account > API Access. Click Add service account, enter a name such as Swell, and under Scopes select mrp.product and mrp.order. Click Create service account and copy the Client ID and Client Secret. The secret is shown only once.
Sandbox and production service accounts only work in their own Cropster environment. If Cropster gave you a sandbox account, use it for your Swell test environment, because orders sent to your production account go into production.
Add it to the app
In Swell, go to Apps > Cropster > Settings and enter the Client ID and Client Secret. Under Products, check that Package size option and Grind option match the names of your product options. Under Orders, choose when orders are sent and the customer type. Click Save settings.
Test the connection
Choose Actions > Test connection. The app requests a token from Cropster and reads one order.
Turn on the integration
Turn on Enable Integration and save. From then on, product and order changes are sent to Cropster as they happen.
Sync your products
Open Cropster sync in the dashboard sidebar and sync products. New products arrive in Cropster as unreviewed, so review them in Cropster before their orders can be produced.
Sync your orders
On Cropster sync, sync orders. Sync products first, because Cropster matches order items by SKU.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 1 to 6 with your production Cropster account.
Each product goes to Cropster with one variant for each active Swell variant, or the product itself when it has no variants:
- The SKU comes from the variant, or the product. Variants without a SKU aren't sent.
- The package size comes from the variant's package size option, named in Package size option. Values such as 250g, 340 grams, 1.5kg, 12 oz, 2 lb or 1/2 lb are matched to Cropster's package sizes, also across units. Without a size option, the app tries the product's Package size field, then the variant name and the product name. Variants without a recognized size aren't sent.
- The grind style comes from the grind option, named in Grind option, or Default grind style.
A product with no variant to send, such as merchandise without a size, isn't sent, and the reason is shown on its Cropster tab. With Products to send set to marked products, only products with Send to Cropster turned on are sent.
Orders are sent when they're paid, or when they're submitted if Send orders when is set to that. Canceled and draft orders aren't sent. Each production order has the Swell order number, the order date, the customer's company or name, and the SKU and quantity of each item whose product is sent to Cropster. Items with the same SKU are added up, and orders without such items aren't sent.
Orders are sent as Customer type, retail by default. Orders from customers in the Wholesale customer group are sent as wholesale.
When an order's items change, it's sent again while its Cropster state is Open. Once Cropster has scheduled or started an order, changes in Swell aren't sent.
Every 15 minutes the app reads the orders changed in Cropster in the last 2 hours, and copies each one's state, fulfillment status and change date to the Swell order with the same number. The order's Cropster tab shows them, and the order list has a Cropster column. Orders created in Cropster itself are ignored.
Cropster sync in the dashboard sidebar sends the products and orders you already have. You choose all records or only those created on or after a date, and a page size of 10, 25 or 50 records. Products and orders each have a progress bar, the number of records sent, skipped and failed, and the list of records that weren't sent with the reason.
The sync runs in your browser, one page at a time, so keep the page open until it's done. If it stops, choose Resume from page N to continue.
To send a product or order right away, open it and choose Actions > Send to Cropster. To send several, select up to 50 in the product or order list and choose Send to Cropster. The app shows how many were sent, skipped or failed.
| Where | What it's for |
| Apps > Cropster > Settings | The service account, the integration switch, and how products and orders are sent. |
| Cropster sync in the sidebar | Sends existing products and orders, with progress and the records that weren't sent. |
| A product's Cropster tab | The package size, the Cropster product ID and review state, when it was last sent and the last error. |
| An order's Cropster tab | The Cropster state and fulfillment status, the Cropster order ID, when it changed and was last sent, and the last error. |
Settings are in Apps > Cropster > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Client ID | From a Cropster service account with the mrp.product and mrp.order scopes. Required. | None |
| Client Secret | That service account's secret. Masked on the settings page. Required. | None |
| Enable Integration | Sends product and order changes as they happen, updates production states, and turns on the sync page and Send to Cropster. | Off |
| Products to send | All products with a SKU and package size, or only products with Send to Cropster turned on. | All products |
| Package size option | Names of the product options that hold the package size, separated by commas. | Size, Weight |
| Grind option | Names of the product options that hold the grind style, separated by commas. | Grind |
| Default grind style | The grind style for variants without a grind option. | Whole Bean |
| Send orders when | When an order is sent: when it's paid or when it's submitted. | Order is paid |
| Customer type | The customer type of production orders: Retail or Wholesale. | Retail |
| Wholesale customer group | Optional. The ID of an account group whose orders are sent as wholesale. | None |
- Only coffee products can be sent, because Cropster needs a package size from its fixed list for every variant.
- Once a variant is created in Cropster, its package size and grind style can't be changed through the app.
- The app doesn't delete products or cancel orders in Cropster. Delete or cancel them in Cropster.
- Changes to an order aren't sent after Cropster has scheduled or started it.
- Production states reach Swell within about 15 minutes. If the integration is off for more than 2 hours, changes made in Cropster during that time come through only when the order changes there again.
- Cropster allows about 5 requests per second. Large bursts of changes, such as a bulk product import, can be rate limited. Swell retries failed changes, and the sync page can send everything again.
When Cropster rejects a product or order, the reason is shown in Error on its Cropster tab.
Check the Client ID and Client Secret, and that the service account has the mrp.product and mrp.order scopes. Sandbox credentials only work with a sandbox account, and production credentials with a production one.
Each variant needs a SKU and a package size Cropster recognizes. Check that Package size option names the option that holds the size, or set Package size on the product's Cropster tab. Then choose Actions > Send to Cropster.
Only items whose products are sent to Cropster are included, so sync products before orders. Check that the order is paid, or submitted, as Send orders when requires. Then choose Actions > Send to Cropster on the order.
New products arrive in Cropster as unreviewed. Review them in Cropster, and check the product's Review state on its Cropster tab.
Check that Enable Integration is on. States are copied every 15 minutes, for orders changed in Cropster in the last 2 hours.
Uninstalling the app stops sending products and orders to Cropster, stops the production state updates, and removes Cropster sync and the Cropster tabs from your dashboard. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Products and orders already in Cropster stay there. If you no longer need the service account, delete it in Cropster under Account > API Access.
| Function | Runs on | What it does |
| product-events | product.created, product.updated, product.variant.created and product.variant.updated | Sends the product and its variants to Cropster. |
| order-events | order.paid, order.submitted and order.updated | Creates the production order, or updates it while it's open. |
| order-status | Every 15 minutes | Copies the state, status and change date of orders changed in Cropster in the last 2 hours. |
| send-to-cropster | The Send to Cropster actions | Sends the selected products or orders right away. |
| test-connection | The Test connection action | Requests a token and reads one order. |
The app stores its fields on products and orders under $app.cropster. Products have cropster_enabled, cropster_package_size, cropster_id, cropster_review_state, cropster_synced_at and cropster_error. Orders have cropster_id, cropster_state, cropster_status, cropster_modified_at, cropster_synced_at and cropster_error. The app writes them without triggering events, so its own updates don't send records again.
The app calls the Cropster RPC API with an OAuth 2.0 client credentials token. Cropster accepts 50 records per request and rejects the whole request if one record is invalid, so the app then resends that batch one record at a time, and each invalid record gets its own error.
Swell builds and maintains the Cropster app. For help with the app, email support@swell.is. For questions about your Cropster account or the API Integration add-on, contact Cropster.