Skip to content
Rigel docs
Open Rigel

Finish a shopping trip

shopping.trip.finish

POST/api/v1/households/{household_id}/commands/shopping.trip.finish

  • Command
  • Rigel runs it
  • Applies offline

Finishes the trip to store_id (or the items checked off with no store, when store_id is left out): saves a trip with those checked items in the order they were checked, takes them off the list, and has Rigel put what was bought away in inventory a moment later. Items other shoppers checked at other stores stay on the list for their own trips. Fails with nothing_checked when nothing was checked for this store. Returns the trip, how many items it has, and how many things will be put away, were left alone as untracked, or still need a usual place.

Parameters#

Finish a shopping trip: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Finish a shopping trip: request body fields
FieldDescription
store_idstring or nulloptional

The store the trip was at. Finishes the items checked at that store; leave out for items checked with no store.

shopped_onstring (date)required

The day of the trip, YYYY-MM-DD, in the household's time zone.

Response#

200 The command was applied.

Finish a shopping trip: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

result.trip_idstringrequired

The new trip.

result.item_countintegerrequired

How many items the trip bought.

result.put_awayobjectrequired
result.put_away.to_put_awayintegerrequired

How many bought things Rigel will put away in inventory, a moment after the trip is saved.

result.put_away.untrackedintegerrequired

How many weren't put away because the household doesn't track them.

result.put_away.no_usual_placeintegerrequired

How many are tracked but have no usual place yet, so Rigel should ask or decide where they go.

result.put_away.on_arrivalintegerrequired

How many Rigel will put away once the order arrives (an order that hasn't arrived yet).

versionintegerrequired

The household version after the command.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Finish a shopping trip: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404store_not_foundAn unknown store is refused.
404not_foundThe household doesn't exist, or you aren't a member of it.
409nothing_checked
  • Nothing checked is refused.
  • Nothing checked at this store is refused even when other stores have items.
409idempotency_key_reusedThe Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

The items checked at the store become a trip, in the order they were checked, and leave the list

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01JC000000000000000000000A",
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0V5R3TK10GZD0WMXQ

{
  "result": {
    "trip_id": "trp_01JC4N0000MBGE5RJ6Q7V6V6T8",
    "item_count": 2,
    "put_away": {
      "to_put_away": 0,
      "untracked": 0,
      "no_usual_place": 2,
      "on_arrival": 0
    }
  },
  "version": 1
}

Another shopper's items checked at another store stay on the list

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01JC000000000000000000000A",
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0RDB7ZRXB0P41H703

{
  "result": {
    "trip_id": "trp_01JC4N0000MBGE5RJ6Q7V6V6T8",
    "item_count": 1,
    "put_away": {
      "to_put_away": 0,
      "untracked": 0,
      "no_usual_place": 1,
      "on_arrival": 0
    }
  },
  "version": 1
}

With no store given, it takes the items checked with no store

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "shopped_on": "2025-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R00AZY5YWEAGQJC36K

{
  "result": {
    "trip_id": "trp_01JC4N0000MBGE5RJ6Q7V6V6T8",
    "item_count": 1,
    "put_away": {
      "to_put_away": 0,
      "untracked": 0,
      "no_usual_place": 1,
      "on_arrival": 0
    }
  },
  "version": 1
}

Put-away counts untracked products and tracked ones with no usual place

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "shopped_on": "2025-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0T6KTK63V6RA3ZK3Y

{
  "result": {
    "trip_id": "trp_01JC4N0000MBGE5RJ6Q7V6V6T8",
    "item_count": 3,
    "put_away": {
      "to_put_away": 1,
      "untracked": 1,
      "no_usual_place": 1,
      "on_arrival": 0
    }
  },
  "version": 1
}

An actor with no person finishes with no shopper

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "shopped_on": "2025-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0KHDXFHZNZQBV9JGW

{
  "result": {
    "trip_id": "trp_01JC4N0000MBGE5RJ6Q7V6V6T8",
    "item_count": 1,
    "put_away": {
      "to_put_away": 0,
      "untracked": 0,
      "no_usual_place": 1,
      "on_arrival": 0
    }
  },
  "version": 1
}

Nothing checked is refused

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "shopped_on": "2025-11-07"
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0H9289XKP2ECK1N6Q

{
  "error": {
    "code": "nothing_checked",
    "message": "Nothing has been checked off for this trip. No changes were applied.",
    "details": {
      "store_id": null
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0H9289XKP2ECK1N6Q"
  }
}

Nothing checked at this store is refused even when other stores have items

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01JC000000000000000000000A",
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "store_id": "sto_01JC000000000000000000000A",
  "shopped_on": "2025-11-07"
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0KE082GCGA0JJ7PHC

{
  "error": {
    "code": "nothing_checked",
    "message": "Nothing has been checked off for this trip. No changes were applied.",
    "details": {
      "store_id": "sto_01JC000000000000000000000A"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0KE082GCGA0JJ7PHC"
  }
}

An unknown store is refused

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "store_id": "sto_01JC000000000000000000000Z",
  "shopped_on": "2025-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01JC000000000000000000000Z",
    shopped_on: "2025-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "store_id": "sto_01JC000000000000000000000Z",
  "shopped_on": "2025-11-07"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0RHN17QTAGXJRMA5P

{
  "error": {
    "code": "store_not_found",
    "message": "That store isn't there any more. No changes were applied.",
    "details": {
      "store_id": "sto_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0RHN17QTAGXJRMA5P"
  }
}

Finish a shopping trip

Saves what was checked off at the store as a trip and takes it off the list. Rigel puts it away in inventory a moment later.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CT8J4JPR94MDYF31AGG3' \
  -d '{
  "store_id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
  "shopped_on": "2026-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CT8J4JPR94MDYF31AGG3",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
    shopped_on: "2026-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CT8J4JPR94MDYF31AGG3

{
  "store_id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
  "shopped_on": "2026-11-07"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CT8JZX0TAJ4TD18B6A7C

{
  "result": {
    "trip_id": "trp_01M6V9CT8JBJVJK865ZH4D2ZZD",
    "item_count": 2,
    "put_away": {
      "to_put_away": 1,
      "untracked": 0,
      "no_usual_place": 1,
      "on_arrival": 0
    }
  },
  "version": 285
}

Finish a trip with nothing checked off

A trip needs at least one item checked off at that store.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CT8N87EACZ6T1Z5J8M4P' \
  -d '{
  "store_id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
  "shopped_on": "2026-11-07"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CT8N87EACZ6T1Z5J8M4P",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    store_id: "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
    shopped_on: "2026-11-07",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/shopping.trip.finish HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CT8N87EACZ6T1Z5J8M4P

{
  "store_id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
  "shopped_on": "2026-11-07"
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01M6V9CT8NH9XBWB0AW6ZYMNTR

{
  "error": {
    "code": "nothing_checked",
    "message": "Nothing has been checked off for this trip. No changes were applied.",
    "details": {
      "store_id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01M6V9CT8NH9XBWB0AW6ZYMNTR"
  }
}

For Rigel#

Rigel's tool for this command is shopping_trip_finish. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel