Sourcing · Contract

11 operations in the sourcing.contract namespace.

sourcing.contract.completeContractMilestone

Mark a milestone complete

POST /rpc/v1/sourcing.contract.completeContractMilestone

Requires permission sourcing.contract.write and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.completeContractMilestone \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.createContract

Create a green purchase contract

POST /rpc/v1/sourcing.contract.createContract

Lines carry the weight and price. The contract’s rolled-up position is DERIVED from them, so a corrected line cannot leave the header out of step.

Requires permission sourcing.contract.write and the green_contracts module on the organization’s plan.

Request

Field	Type	Required
`contractNumber`	string	yes
`partnerId`	string	yes
`currency`	string	no
`priceType`	`fixed` \| `differential` \| `to_be_fixed` \| `formula`	no
`incoterm`	`EXW` \| `FCA` \| `FAS` \| `FOB` \| `CFR` \| `CIF` \| `CPT` \| `CIP` \| `DAP` \| `DPU` \| `DDP`	no
`contractDate`	string	no
`paymentTermsDays`	integer	no
`notes`	string	no
`lines`	object[]	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.createContract \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.createContractMilestone

Add a milestone to a contract

POST /rpc/v1/sourcing.contract.createContractMilestone

Requires permission sourcing.contract.write and the green_contracts module on the organization’s plan.

Request

Field	Type	Required
`contractId`	string	yes
`kind`	`contract_signed` \| `fixation` \| `shipment` \| `vessel_departure` \| `vessel_arrival` \| `customs_clearance` \| `warehouse_receipt` \| `sample_approval` \| `payment`	yes
`dueAt`	string	yes
`notes`	string	no

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.createContractMilestone \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.createContractShipment

Book a shipment against a contract

POST /rpc/v1/sourcing.contract.createContractShipment

Requires permission sourcing.contract.write and the green_contracts module on the organization’s plan.

Request

Field	Type	Required
`contractId`	string	yes
`reference`	string	yes
`weightKg`	string	yes
`vessel`	string	no
`carrier`	string	no
`containerNumber`	string	no
`portOfLoading`	string	no
`portOfDischarge`	string	no
`etd`	string	no
`eta`	string	no
`destinationLocationId`	string	no

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.createContractShipment \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.getContract

Get a contract with its lines

POST /rpc/v1/sourcing.contract.getContract

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Requires permission sourcing.contract.read and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.getContract \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.listContractMilestones

Milestones across contracts

POST /rpc/v1/sourcing.contract.listContractMilestones

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

The cost of missing a fixation or a vessel is asymmetric — expensive, and recoverable only if noticed early — so this is org-wide by default rather than per contract.

Requires permission sourcing.contract.read and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.listContractMilestones \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.listContracts

List green purchase contracts

POST /rpc/v1/sourcing.contract.listContracts

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Requires permission sourcing.contract.read and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no
`page`	object	no

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.listContracts \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.listContractShipments

List shipments

POST /rpc/v1/sourcing.contract.listContractShipments

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Requires permission sourcing.contract.read and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no
`page`	object	no

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.listContractShipments \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.listOpenPositions

What is committed and not yet received

POST /rpc/v1/sourcing.contract.listOpenPositions

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

The green buyer’s daily question. Outstanding weight is where a roastery’s money sits between signing a contract and the coffee arriving.

Requires permission sourcing.contract.read and the green_contracts module on the organization’s plan.

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.listOpenPositions \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.receiveContractShipment

Receive a shipment into inventory

POST /rpc/v1/sourcing.contract.receiveContractShipment

Creates a green lot per line, books its opening weight through the ledger, and copies the contract’s pricing into cost components — so a lot’s landed cost is derived from what was bought rather than typed in twice. Atomic: a half-received shipment is worse than a failed one, because nobody knows to look for it.

Requires permission sourcing.contract.write and the green_contracts module on the organization’s plan.

Request

Field	Type	Required
`shipmentId`	string	yes
`locationId`	string	no
`lines`	object[]	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.receiveContractShipment \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

sourcing.contract.updateContractStatus

Change a contract’s status

POST /rpc/v1/sourcing.contract.updateContractStatus

Requires permission sourcing.contract.approve and the green_contracts module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes
`status`	`draft` \| `pending` \| `confirmed` \| `partially_shipped` \| `shipped` \| `arrived` \| `closed` \| `canceled` \| `defaulted`	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/sourcing.contract.updateContractStatus \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'