Add summary statistics to contract retrieve endpoint and remove unassigned codes from /codes output. Add filtering on assigned + redeemed statuses by dsubak · Pull Request #3705 · mitodl/mitxonline

dsubak · 2026-06-25T18:27:28Z

Description (What does it do?)

Now that we've paginated the API, the frontend doesn't have a particularly good way to grab the breakdown of codes to show to the contract manager:

Previously, these were just calculated by looking at the total rowset returned from /codes.

This PR attempts to put that info into the contract retrieve endpoint instead - that endpoint already looked like it was outputting some values like that (most notably a miscalculated total_codes value), so it seemed reasonable to add here.

Additionally, this PR removes unassigned codes from the response entirely.

We no longer actually intend to show unassigned codes in the UI - contract admins shouldn't need to see them as the assign endpoints already handle distributing them automagically. The only codepath which returned them is for contracts which don't have automatic membership types AND a max_learners set (the former case never returns any codes, the latter returns the first one if it exists). We considered adding a query param to filter those out, but as this endpoint already has a bit too many edge cases, we thought this might make it easier to reason about - this makes /codes more like "used/assigned codes"

If we decide later that we do need them in this payload, we can either add a kwarg or create a new endpoint for "available codes".

Lastly, this PR adds filtering on the "status" of a code for the /codes endpoint. Since we've removed unassigned codes from the payload, we only have to worry about support for "assigned" and "redeemed" codes

Screenshots (if appropriate):

How can this be tested?

In addition to all tests passing, manual testing can be performed in the following manner.

Common setup

With a b2b contract set up, assign a few codes using a few different emails and users. You can get the list of codes by visiting http://mitxonline.odl.local:9080/api/v0/b2b/manager/organizations/<org_id>/contracts/<contract_id>/codes/, and it's easiest to assign the codes using the swagger UI for /assign

To test the filtering behavior, you'll want to redeem a few codes using the attach API.

At the end of setup, you should have at least a few values in redeemed, assigned and unassigned to make subsequent steps easier.

Removal of Unassigned codes from /codes

As long as you've got at least one code that has not been assigned or redeemed, simply hit http://mitxonline.odl.local:9080/api/v0/b2b/manager/organizations/<org_id>/contracts/<contract_id>/codes/ and observe that it is not returned in the resultset.
- If you've got a lot of codes, in assigned/redeemed state, you can specify a very large page size to get it all in one request for verification

Summary Statistics

Visit http://mitxonline.odl.local:9080/api/v0/b2b/manager/organizations/<org_id>/contracts/<contract_id>/
You should observe that the following fields are populated in the response and are reflective of your contract. The only one which is not self-explanatory is total_codes, and that should match the max_learners set on the contract itself.

total_codes
assigned_codes
unassigned_codes
redeemed_codes

Status filtering

Visit http://mitxonline.odl.local:9080/api/v0/b2b/manager/organizations/<org_id>/contracts/<contract_id>/codes/ and specify a status parameter of either "assigned" or "redeemed"
You should observe that only codes in the matching status are returned.
Additionally, if you specify a search_term AND a status parameter, both filters should be properly applied.

Additional Information

Take note - this PR is a branch off of #3685; in order to simplify the release, this branch will be merged into that PR and the whole thing will be released in one shot.

…ed count of total_codes + annotation). Remove unassigned codes from the output since we no longer show that to anyone.

dsubak · 2026-06-25T18:28:50Z

                organization__organization_users__is_manager=True,
            )
        )
+        if self.action == "retrieve":


Currently only used for the contract retrieve endpoints where we calculate summary stats.

github-actions · 2026-06-25T18:29:01Z

OpenAPI Changes

Show/hide ## Changes for v0.yaml:

## Changes for v0.yaml:
4 changes: 0 error, 0 warning, 4 info
info	[response-required-property-added] at head/openapi/specs/v0.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `assigned_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v0.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `redeemed_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v0.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `unassigned_codes` to the response with the `200` status

info	[new-optional-request-parameter] at head/openapi/specs/v0.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/codes/
		added the new optional `query` request parameter `status`



## Changes for v1.yaml:
4 changes: 0 error, 0 warning, 4 info
info	[response-required-property-added] at head/openapi/specs/v1.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `assigned_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v1.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `redeemed_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v1.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `unassigned_codes` to the response with the `200` status

info	[new-optional-request-parameter] at head/openapi/specs/v1.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/codes/
		added the new optional `query` request parameter `status`



## Changes for v2.yaml:
4 changes: 0 error, 0 warning, 4 info
info	[response-required-property-added] at head/openapi/specs/v2.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `assigned_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v2.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `redeemed_codes` to the response with the `200` status

info	[response-required-property-added] at head/openapi/specs/v2.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/
		added the required property `unassigned_codes` to the response with the `200` status

info	[new-optional-request-parameter] at head/openapi/specs/v2.yaml
	in API GET /api/v0/b2b/manager/organizations/{parent_lookup_organization}/contracts/{id}/codes/
		added the new optional `query` request parameter `status`

Unexpected changes? Ensure your branch is up-to-date with main (consider rebasing).

… in cases where max_learners > 0 anymore

…st count of discounts

…regenerate spec

dsubak · 2026-06-26T18:34:40Z

@jkachel and @daniellefrappier18 - pulling this out of draft and into ready for review!

Ya'll obviously both already looked at it a little - the only material change since then is to add the ability to filter on status. Let me know if there are any questions!

daniellefrappier18

Tested this out in mitodl/mit-learn#3530 and everything is working as expected on my end. :)

jkachel

LGTM 👍

Add summary statistics to contract retrieve endpoint (and remove bust…

9abc40e

…ed count of total_codes + annotation). Remove unassigned codes from the output since we no longer show that to anyone.

dsubak commented Jun 25, 2026

View reviewed changes

Fix test to account for the fact that we dont return unassigned codes…

4d96745

… in cases where max_learners > 0 anymore

dsubak marked this pull request as draft June 25, 2026 19:15

daniellefrappier18 reviewed Jun 25, 2026

View reviewed changes

Comment thread b2b/views/v0/manager.py

jkachel reviewed Jun 25, 2026

View reviewed changes

Comment thread b2b/serializers/v0/manager.py Outdated

dsubak added 2 commits June 26, 2026 08:38

Total for display is always just max_learners, no need to check again…

c6a57ff

…st count of discounts

Pull is_redeemed_attachment_record into utils

7af6a2c

dsubak marked this pull request as ready for review June 26, 2026 12:40

Adds status filter, tests for composed status + search_term filters, …

7dbc25d

…regenerate spec

dsubak added the Needs Review label Jun 26, 2026

dsubak changed the title ~~Add summary statistics to contract retrieve endpoint and remove unassigned codes from /codes output.~~ Add summary statistics to contract retrieve endpoint and remove unassigned codes from /codes output. Add filtering on assigned + redeemed statuses Jun 26, 2026

dsubak requested review from daniellefrappier18 and jkachel June 26, 2026 18:33

daniellefrappier18 approved these changes Jun 26, 2026

View reviewed changes

jkachel approved these changes Jun 26, 2026

View reviewed changes

dsubak merged commit 9ba4782 into dansubak/202606_paginated_codes Jun 26, 2026
5 checks passed

dsubak deleted the dansubak/202606_paginated_codes_means_paginated_problems branch June 26, 2026 19:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add summary statistics to contract retrieve endpoint and remove unassigned codes from /codes output. Add filtering on assigned + redeemed statuses#3705

Add summary statistics to contract retrieve endpoint and remove unassigned codes from /codes output. Add filtering on assigned + redeemed statuses#3705
dsubak merged 5 commits into
dansubak/202606_paginated_codesfrom
dansubak/202606_paginated_codes_means_paginated_problems

dsubak commented Jun 25, 2026 •

edited

Loading

Uh oh!

dsubak Jun 25, 2026

Uh oh!

github-actions Bot commented Jun 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

dsubak commented Jun 26, 2026

Uh oh!

daniellefrappier18 left a comment

Uh oh!

jkachel left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

dsubak commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (What does it do?)

Screenshots (if appropriate):

How can this be tested?

Removal of Unassigned codes from /codes

Summary Statistics

Status filtering

Additional Information

Uh oh!

dsubak Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenAPI Changes

Uh oh!

Uh oh!

Uh oh!

dsubak commented Jun 26, 2026

Uh oh!

daniellefrappier18 left a comment

Choose a reason for hiding this comment

Uh oh!

jkachel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dsubak commented Jun 25, 2026 •

edited

Loading

github-actions Bot commented Jun 25, 2026 •

edited

Loading